Cosmopolitan C Library

This function first tries to trigger your SIGABRT handler. If the signal handler returns, then signal(SIGABRT, SIG_DFL) is called before SIGABRT is raised again.

@noreturn

@asyncsignalsafe

@see libc/runtime/abort.c

abs

Returns absolute value of 32-bit integer.

@param

int x

@return

int

@note labs(LONG_MIN) returns LONG_MIN unless -ftrapv

@note consider ABS() to avoid narrowing

@see libc/fmt/abs.c

accept

Creates client socket file descriptor for incoming connection.

@param

int fd: is the server socket file descriptor
struct sockaddr* out_addr: will receive the remote address
unsigned int* inout_addrsize: provides and receives addr's byte length

@return

int: client fd which needs close(), or -1 w/ errno

@cancellationpoint

@asyncsignalsafe

@restartable (unless SO_RCVTIMEO)

@see libc/sock/accept.c

accept4

Creates client socket file descriptor for incoming connection.

@param

int fd: is the server socket file descriptor
struct sa* out_addr: will receive the remote address
unsigned int* inout_addrsize: provides and receives out_addr's byte length
int flags: can have SOCK_{CLOEXEC,NONBLOCK}, which may apply to both the newly created socket and the server one

@return

int: client fd which needs close(), or -1 w/ errno

@cancellationpoint

@asyncsignalsafe

@restartable (unless SO_RCVTIMEO)

@see libc/sock/accept4.c

access

Checks if effective user can access path in particular ways.

This is equivalent to saying:

faccessat(AT_FDCWD, path, mode, 0);

@param

const char* path: is a filename or directory
int mode: can be R_OK, W_OK, X_OK, F_OK

@return

int: 0 if ok, or -1 w/ errno

@see faccessat() for further documentation

@asyncsignalsafe

@see libc/calls/access.c

acos

Returns arc cosine of 𝑥.

@param

double x

@return

double: value in range [0,M_PI]; NAN if 𝑥 ∈ {NAN,+INFINITY,-INFINITY}; NAN if 𝑥 ∉ [-1,1]

@see libc/tinymath/acos.c

acosf

Returns arc cosine of 𝑥.

@param

𝑥: is float scalar in low quarter of %xmm0

@return

: float scalar in low quarter of %xmm0

@see libc/tinymath/acosf-tiny.S

acosh

Returns inverse hyperbolic cosine of 𝑥.

@param

double x

@return

double

@define acosh(x) = log(x + sqrt(x*x-1))

@see libc/tinymath/acosh.c

acoshf

Returns inverse hyperbolic cosine of 𝑥.

@param

float x

@return

float

@define acosh(x) = log(x + sqrt(x*x-1))

@see libc/tinymath/acoshf.c

acoshl

Returns inverse hyperbolic cosine of 𝑥.

@param

long double x

@return

long double

@see libc/tinymath/acoshl.c

acosl

Returns arc cosine of 𝑥.

@param

𝑥: is an 80-bit long double passed on stack in 16-bytes

@return

: result of computation on FPU stack in %st

@define atan2(fabs(sqrt((1-𝑥)*(1+𝑥))),𝑥)

@domain -1 ≤ 𝑥 ≤ 1

@see libc/tinymath/acosl.S

AcquireToken

Atomically decrements signed byte index if it's positive.

Multiple threads are able to call this method, to determine if enough tokens exist to perform an operation. Return values greater than zero mean a token was atomically acquired. Values less than, or equal zero means the bucket is empty. There must exist 1 << c signed bytes (or buckets) in the b array.

Since this design uses signed bytes, your returned number may be used to control how much burstiness is allowed. For example:

int t = AcquireToken(tok.b, ip, 22);
if (t < 64) {
  if (t > 8) write(client, "HTTP/1.1 429 \r\n\r\n", 17);
  close(client);
  return;
}

Could be used to send rejections to clients that exceed their tokens, whereas clients who've grossly exceeded their tokens, could simply be dropped.

@param

_Atomic char* b: is array of token buckets
unsigned int x: is ipv4 address
int c: is cidr

@return

int

@see net/http/tokenbucket.c

addmntent

@param

struct FILE* f
struct mnt* mnt

@return

int

@see third_party/musl/mntent.c

__addvdi3

Returns 𝑥+𝑦, aborting on overflow.

@param

rdi: is int64 𝑥
rsi: is int64 𝑦

@return

: rax is 𝑥+𝑦

@see -ftrapv

@see libc/intrin/addvdi3.S

__addvsi3

Returns 𝑥+𝑦, aborting on overflow.

@param

edi: is int32 𝑥
esi: is int32 𝑦

@return

: eax is 𝑥+𝑦

@see -ftrapv

@see libc/intrin/addvsi3.S

__addvti3

Returns 𝑥+𝑦, aborting on overflow.

@param

rdi:rsi: is int128 𝑥
rdx:rcx: is int128 𝑦

@return

: rdx:rax is 𝑥+𝑦

@see -ftrapv

@see libc/intrin/addvti3.S

adler32

Updates running Adler-32 checksum with the bytes buf[0..len-1] and return the updated checksum. If buf is Z_NULL, this function returns the required initial value for the checksum.

@return

unsigned long

@see third_party/zlib/zlib.h

adler32_combine

Combine two Adler-32 checksums into one. For two sequences of bytes, seq1 and seq2 with lengths len1 and len2, Adler-32 checksums were calculated for each, adler1 and adler2. adler32_combine() returns the Adler-32 checksum of seq1 and seq2 concatenated, requiring only adler1, adler2, and len2. Note that the off_t type (like off_t) is a signed integer. If len2 is negative, the result has no meaning or utility.

@return

unsigned long

@see third_party/zlib/zlib.h

adler32_z

Same as adler32(), but with a size_t length.

@return

unsigned long

@see third_party/zlib/zlib.h

alarm

Asks for single-shot SIGALRM to be raise()'d after interval.

@param

unsigned int seconds: until we get signal, or 0 to reset previous alarm()

@return

unsigned int: seconds previous alarm() had remaining, or -1u w/ errno

@see setitimer()

@asyncsignalsafe

@see libc/calls/alarm.c

aligned_alloc

Same as memalign(a, n) but requires IS2POW(a).

@param

unsigned long a
unsigned long n: number of bytes needed

@return

void*: memory address, or NULL w/ errno

@throw EINVAL if !IS2POW(a)

@see pvalloc()

@threadsafe

@see libc/mem/aligned_alloc.c

alphasort

@param

struct dirent** a
struct dirent** b

@return

int

@see libc/stdio/alphasort.c

appendd

Appends data to buffer, e.g.

char *b = 0;
appendd(&b, "hello", 5);
free(b);

The resulting buffer is guaranteed to be NUL-terminated, i.e. !b[appendz(b).i] will be the case.

@param

char** b
void* s: may contain nul characters and may be null if l is zero
unsigned long l: is byte length of s

@return

long: bytes appended (always l) or -1 if ENOMEM

@see appendz(b).i to get buffer length

@note 20% faster than appends()

@see libc/stdio/appendd.c

appendf

Appends formatted string to buffer, e.g.

char *b = 0;
appendf(&b, "hello %d\n", 123);
free(b);

@param

char** b
const char* fmt
...

@return

long: bytes appended or -1 if ENOMEM

@see appendz(b).i to get buffer length

@note O(1) amortized buffer growth

@see libc/stdio/appendf.c

appendHostInfo

@param

struct HostAdapterInfoNode* parentInfoNode
const char* baseName
struct NtIpAdapterAddresses* aa
struct NtIpAdapterUnicastAddress** ptrUA
struct NtIpAdapterPrefix** ptrAP
int count

@return

struct HostAdapterInfoNode*

@see libc/calls/ioctl_siocgifconf-nt.c

appendr

Resets length of append buffer, e.g.

char *b = 0;
appends(&b, "hello");
appendr(&b, 1);
assert(!strcmp(b, "h"));
appendr(&b, 0);
assert(!strcmp(b, ""));
free(b);

If i is greater than the current length then the extra bytes are filled with NUL characters. If i is less than the current length then memory is released to the system.

The resulting buffer is guaranteed to be NUL-terminated, i.e. !b[appendz(b).i] will be the case even if both params are 0.

@param

char** b
unsigned long i

@return

long: i or -1 if ENOMEM

@see appendz(b).i to get buffer length

@see libc/stdio/appendr.c

AppendResourceReport

Generates process resource usage report.

@param

char** b
struct rusage* ru
const char* nl

@return

void

@see libc/log/appendresourcereport.c

appends

Appends string to buffer, e.g.

char *b = 0;
appends(&b, "hello");
free(b);

The resulting buffer is guaranteed to be NUL-terminated, i.e. !b[appendz(b).i] will be the case.

@param

char** b
const char* s

@return

long: bytes appended (always strlen(s)) or -1 if ENOMEM

@see appendz(b).i to get buffer length

@note 2x faster than appendf()

@see libc/stdio/appends.c

AppendStrList

@param

struct StrList* sl

@return

int

@see libc/stdio/appendstrlist.c

appendw

Appends character or word-encoded string to buffer.

Up to eight characters can be appended. For example:

appendw(&s, 'h'|'i'<<8);
appendw(&s, READ64LE("hi\0\0\0\0\0"));

Are equivalent to:

appends(&s, "hi");

The special case:

appendw(&s, 0);

Will append a single NUL character.

This function is slightly faster than appendd() and appends(). Its main advantage is it improves code size in functions that call it.

The resulting buffer is guaranteed to be NUL-terminated, i.e. !b[appendz(b).i] will be the case.

@param

char** b
unsigned long w

@return

long: bytes appended or -1 if ENOMEM

@see appendz(b).i to get buffer length

@see libc/stdio/appendw.c

appendz

Returns size of append buffer.

@param

char* p: must be 0 or have been allocated by an append*() function

@return

struct z: i is number of bytes stored in buffer; n is number of bytes in allocation

@see libc/stdio/appendz.c

arch_prctl

Changes x86 segment registers.

Support for segment registers is spotty across platforms. See the table of tested combinations below.

This wrapper has the same weird ABI as the Linux Kernel. The type Cosmopolitan type signature of the prototype for this function is variadic, so no value safety checking will be performed w/o asan.

Cosmopolitan Libc initializes your process by default, to use the segment register %fs, for thread-local storage. To safely disable this TLS you need to either set __tls_enabled to 0, or you must follow the same memory layout assumptions as your C library. When TLS is disabled you can't use threads unless you call clone() and that's not really a good idea since errno won't be thread-safe.

Please note if you're only concerned about running on Linux, then consider using Cosmopolitan's fsgsbase macros which don't need to issue system calls to change %fs and %gs. See _have_fsgsbase() to learn more.

@param

int code

may be

ARCH_SET_FS works on Linux, FreeBSD, NetBSD, OpenBSD, Metal
ARCH_GET_FS works on Linux, FreeBSD, NetBSD, OpenBSD, Metal
ARCH_SET_GS works on Linux, FreeBSD, NetBSD, XNU, Metal
ARCH_GET_GS works on Linux, FreeBSD, NetBSD, Metal

long addr

is treated as intptr_t when setting a register, and is an output parameter (i.e. intptr_t *) when reading one

...

@return

int

@raise ENOSYS if operating system didn't support changing code

@raise EINVAL if code wasn't valid

@raise EFAULT if ARCH_SET_FS or ARCH_SET_GS was used and memory pointed to by addr was invalid

@see _have_fsgsbase()

@see libc/runtime/arch_prctl.c

AreMemoryIntervalsOk

@param

struct _mmi* mm

@return

_Bool

@see libc/intrin/arememoryintervalsok.c

__arena_pop

Pops memory arena.

This pops the most recently created arena, freeing all the memory that was allocated between the push and pop arena calls. If this is the last arena on the stack, then the old malloc hooks are restored.

@return

void

@see __arena_push()

@see libc/mem/arena.c

__arena_push

Pushes memory arena.

This allocator gives a ~3x performance boost over dlmalloc, mostly because it isn't thread safe and it doesn't do defragmentation.

Calling this function will push a new arena. It may be called multiple times from the main thread recursively. The first time it's called, it hooks all the regular memory allocation functions. Any allocations that were made previously outside the arena, will be passed on to the previous hooks. Then, the basic idea, is rather than bothering with free() you can just call __arena_pop() to bulk free.

Arena allocations also have a slight size advantage, since 32-bit pointers are always used. The maximum amount of arena memory is 805,175,296 bytes.

@return

void

@see __arena_pop()

@see libc/mem/arena.c

__arg_max

Returns ARG_MAX for host platform.

@return

int

@see libc/runtime/getargmax.c

__asan_check

Checks validity of memory range.

This is normally abstracted by the compiler. In some cases, it may be desirable to perform an ASAN memory safety check explicitly, e.g. for system call wrappers that need to vet memory passed to the kernel, or string library routines that use the noasan keyword due to compiler generated ASAN being too costly. This function is fast especially for large memory ranges since this takes a few picoseconds for each byte.

@param

void* p: is starting virtual address
long n: is number of bytes to check

@return

struct f: kind is 0 on success or <0 if invalid; shadow points to first poisoned shadow byte

@see libc/intrin/asan.c

__asan_check_str

Checks validity of nul-terminated string.

This is similar to __asan_check(p, 1) except it checks the validity of the entire string including its trailing nul byte, and goes faster than calling strlen() beforehand.

@param

const char* p: is starting virtual address

@return

struct f: kind is 0 on success or <0 if invalid; shadow points to first poisoned shadow byte

@see libc/intrin/asan.c

__asan_is_valid

Checks memory validity of memory region.

@param

void* p
long n

@return

_Bool

@see libc/intrin/asan.c

__asan_is_valid_iov

Checks memory validity of iov array and each buffer it describes.

@param

struct iovec* iov
int iovlen

@return

_Bool

@see libc/intrin/asan.c

__asan_is_valid_str

Checks memory validity of nul-terminated string.

@param

const char* p

@return

_Bool

@see libc/intrin/asan.c

__asan_is_valid_strlist

Checks memory validity of null-terminated nul-terminated string list.

@param

char** p

@return

_Bool

@see libc/intrin/asan.c

asctime

@param

struct tm* timeptr

@return

char*

@see libc/time/asctime.c

asctime_r

@param

struct tm* timeptr
char* buf

@return

char*

@see libc/time/asctime.c

asin

Returns arc sine of 𝑥.

@param

double x

@return

double: value in range [-M_PI/2,M_PI/2]; NAN if 𝑥 ∈ {NAN,+INFINITY,-INFINITY}; NAN if 𝑥 ∉ [-1,1]

@see libc/tinymath/asin.c

asinf

Returns arc sine of 𝑥.

@param

𝑥: is float scalar in low quarter of %xmm0

@return

: float scalar in low quarter of %xmm0

@see libc/tinymath/asinf-tiny.S

asinh

Returns inverse hyperbolic sine of 𝑥.

@param

double x

@return

double

@define asinh(x) = sign(x)*log(|x|+sqrt(x*x+1)) ~= x - x^3/6 + o(x^5)

@see libc/tinymath/asinh.c

asinhf

Returns inverse hyperbolic sine of 𝑥.

@param

float x

@return

float

@define asinh(x) = sign(x)*log(|x|+sqrt(x*x+1)) ~= x - x^3/6 + o(x^5)

@see libc/tinymath/asinhf.c

asinhl

Returns inverse hyperbolic sine of 𝑥.

@param

long double x

@return

long double

@define asinh(x) = sign(x)*log(|x|+sqrt(x*x+1)) ~= x - x^3/6 + o(x^5)

@see libc/tinymath/asinhl.c

asinl

Returns arc sine of 𝑥.

@param

𝑥: is an 80-bit long double passed on stack in 16-bytes

@return

: result of computation on FPU stack in %st

@define atan2(𝑥,sqrt((1-𝑥)*(1+𝑥)))

@domain -1 ≤ 𝑥 ≤ 1

@see libc/tinymath/asinl.S

asprintf

Formats string, allocating needed memory.

@param

char** strp
const char* fmt
...

@return

int: bytes written (excluding NUL) or -1 w/ errno

@see xasprintf() for a better API

@threadsafe

@see libc/mem/asprintf.c

__assert_disable

Disables assert() failures at runtime.

@type

_Bool

@see libc/intrin/assertdisable.c

atan

Returns arc tangent of 𝑥.

@param

𝑥: is double scalar in low half of %xmm0

@return

: double scalar in low half of %xmm0

@see libc/tinymath/atan-tiny.S

atan2l

Returns arc tangent of 𝑦/𝑥.

@param

𝑥: is an 80-bit long double passed on stack in 16-bytes
𝑦: is an 80-bit long double passed on stack in 16-bytes

@return

: result of computation on FPU stack in %st

@see libc/tinymath/atan2l.S

atanf

Returns arc tangent of 𝑥.

@param

𝑥: is float scalar in low quarter of %xmm0

@return

: float scalar in low quarter of %xmm0

@see libc/tinymath/atanf-tiny.S

atanh

Returns inverse hyperbolic tangent of 𝑥.

@param

double x

@return

double

@define x ? log1p(2 * x / (1 - x)) / 2 : x

@see libc/tinymath/atanh.c

atanhf

Returns inverse hyperbolic tangent of 𝑥.

@param

float x

@return

float

@define x ? log1p(2 * x / (1 - x)) / 2 : x

@see libc/tinymath/atanhf.c

atanhl

Returns inverse hyperbolic tangent of 𝑥.

@param

long double x

@return

long double

@define x ? log1p(2 * x / (1 - x)) / 2 : x

@see libc/tinymath/atanhl.c

atanl

Returns arc tangent of 𝑥.

              1  3   1  5   1  7   1  9    1  11
atan(𝑥) = 𝑥 - - 𝑥  + - 𝑥  - - 𝑥  + - 𝑥  - -- 𝑥   ...
              3      5      7      9      11

@param

𝑥: is an 80-bit long double passed on stack in 16-bytes

@return

: result of computation on FPU stack in %st

@define atan(𝑥) = Σₙ₌₀₋∞ 2²ⁿ(𝑛!)²/(𝟸𝑛+𝟷)!(𝑥²ⁿ⁺¹/(𝑥²+𝟷)ⁿ⁺¹)

@see libc/tinymath/atanl.S

atexit

Adds global destructor.

Destructors are called in reverse order. They won't be called if the program aborts or _exit() is called. Invocations of this function are usually generated by the C++ compiler.

@param

void(*)() f

@return

int: 0 on success or nonzero if out of space

@see libc/intrin/atexit.c

atof

Converts string to double.

@param

const char* s

@return

double

@see third_party/gdtoa/atof.c

atoi

Decodes decimal integer from ASCII string.

atoi 10⁸              22𝑐         7𝑛𝑠
strtol 10⁸            37𝑐        12𝑛𝑠
strtoul 10⁸           35𝑐        11𝑛𝑠
wcstol 10⁸            30𝑐        10𝑛𝑠
wcstoul 10⁸           30𝑐        10𝑛𝑠
strtoimax 10⁸         80𝑐        26𝑛𝑠
strtoumax 10⁸         78𝑐        25𝑛𝑠
wcstoimax 10⁸         77𝑐        25𝑛𝑠
wcstoumax 10⁸         76𝑐        25𝑛𝑠

@param

const char* s: is a non-null nul-terminated string

@return

int: the decoded signed saturated integer

@raise ERANGE on overflow

@see libc/fmt/atoi.c

atol

Decodes decimal integer from ASCII string.

@param

const char* s: is a non-null nul-terminated string

@return

long: the decoded signed saturated integer

@see libc/fmt/atol.c

atoll

Decodes decimal number from ASCII string.

@param

const char* s: is a non-null nul-terminated string

@return

long: the decoded signed saturated integer

@see libc/fmt/atoll.c

AttachDebugger

Launches GDB debugger GUI for current process.

This function abstracts the toilsome details of configuring the best possible UX for debugging your app, for varying levels of available information, on most of the various platforms.

Before calling this function, consider placing ShowCrashReports() in your main function and calling DebugBreak() wherever you want; it's safer. Also note the "GDB" environment variable can be set to empty string, as a fail-safe for disabling this behavior.

@param

long continuetoaddr: can be a code address, 0, or -1 for auto

@return

int: gdb pid if continuing, 0 if detached, or -1 w/ errno

@note this is called via eponymous spinlock macro wrapper

@see libc/log/attachdebugger.c

balloc

Allocates page-guarded buffer.

@param

struct GuardedBuffer* b: is metadata object owned by caller, initialized to zero for first call; subsequent calls will resize
unsigned int a: is alignment requirement in bytes, e.g. 1,2,4,8,16,...
unsigned long n: is buffer size in bytes

@return

void*: b->p

@see ralloc()

@deprecated

@see libc/mem/balloc.c

basename

Returns pointer to last filename component in path, e.g.

path     │ dirname() │ basename()
─────────────────────────────────
0        │ .         │ .
.        │ .         │ .
..       │ .         │ ..
/        │ /         │ /
usr      │ .         │ usr
/usr/    │ /         │ usr
/usr/lib │ /usr      │ lib

Both / and \ are are considered valid component separators on all platforms. Trailing slashes are ignored. We don't grant special consideration to things like foo/., c:/, \\?\Volume, etc.

@param

char* path: is UTF-8 and may be mutated, but not expanded in length

@return

char*: pointer to path, or inside path, or to a special r/o string

@see dirname()

@see SUSv2

@see libc/fmt/basename.c

bcopy

Moves memory the BSD way.

Please use memmove() instead. Note the order of arguments.

@param

void* src
void* dest
unsigned long n

@return

void

@see libc/intrin/bcopy.c

_bextra

Extracts bit field from array.

@param

const unsigned int* p
unsigned long i
char b

@return

unsigned int

@see libc/intrin/bextra.c

bfree

Frees memory return by balloc().

@param

struct GuardedBuffer* b

@return

void

@deprecated

@see libc/mem/bfree.c

bind

Assigns local address and port number to socket, e.g.

struct sockaddr_in in = {AF_INET, htons(12345), {htonl(0x7f000001)}};
int fd = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
bind(fd, &in, sizeof(in));

@param

int fd: is the file descriptor returned by socket()
struct sa* addr: is usually the binary-encoded ip:port on which to listen
unsigned int addrsize: is the byte-length of addr's true polymorphic form

@return

int: 0 on success or -1 w/ errno

@error ENETDOWN, EPFNOSUPPORT, etc.

@asyncsignalsafe

@see libc/sock/bind.c

bing

Turns binary octet into unicode glyph representation.

Cosmopolitan displays RADIX-256 numbers using these digits:

 0123456789abcdef
0 ☺☻♥♦♣♠•◘○◙♂♀♪♫☼
1►◄↕‼¶§▬↨↑↓→←∟↔▲▼
2 !"#$%&'()*+,-./
30123456789:;<=>?
4@ABCDEFGHIJKLMNO
5PQRSTUVWXYZ[\]^_
6`abcdefghijklmno
7pqrstuvwxyz{|}~⌂
8ÇüéâäàåçêëèïîìÄÅ
9ÉæÆôöòûùÿÖÜ¢£¥€ƒ
aáíóúñÑªº¿⌐¬½¼¡«»
b░▒▓│┤╡╢╖╕╣║╗╝╜╛┐
c└┴┬├─┼╞╟╚╔╩╦╠═╬╧
d╨╤╥╙╘╒╓╫╪┘┌█▄▌▐▀
eαßΓπΣσμτΦΘΩδ∞φε∩
f≡±≥≤⌠⌡÷≈°∙·√ⁿ²■λ

IBM designed these glyphs for the PC to map onto the display bytes at (char *)0xb8000. Because IBM authorized buyers of its PCs to inspect and/or modify this region of memory, it became widely understood by many developers as a quick way to visualize arbitrary data that's so superior to hexdump -- a use-case that's lived on longer than the CGA graphics card for which it was designed.

@param

int b: is binary octet to pictorally represent
int intent: controls canonical multimappings: ∅␀ ,\n◙,ε∊∈€, λ,etc.

@return

int

@see unbing() for inverse

@see libc/fmt/bing.c

bingblit

@param

int ys
int xs
UNKNOWN M
int yn
int xn

@return

short*

@see libc/x/bingblit.c

_bitreverse16

Reverses bits in 16-bit word.

@param

int x

@return

int

@see libc/intrin/bitreverse16.c

_bitreverse32

Reverses bits in 32-bit word.

@param

unsigned int x

@return

unsigned int

@see libc/intrin/bitreverse32.c

_bitreverse64

Reverses bits in 64-bit word.

@param

unsigned long x

@return

unsigned long

@see libc/intrin/bitreverse64.c

_bitreverse8

Reverses bits in 8-bit word.

@param

int x

@return

int

@see libc/intrin/bitreverse8.c

BLAKE2B256

Computes blake2b 256bit message digest.

blake2b256 n=0                     191 nanoseconds
blake2b256 n=8                      23 ns/byte         40,719 kb/s
blake2b256 n=31                      6 ns/byte            153 mb/s
blake2b256 n=32                      6 ns/byte            158 mb/s
blake2b256 n=63                      3 ns/byte            312 mb/s
blake2b256 n=64                      3 ns/byte            317 mb/s
blake2b256 n=128                     1 ns/byte            640 mb/s
blake2b256 n=256                     1 ns/byte            662 mb/s
blake2b256 n=22851                   1 ns/byte            683 mb/s

@param

void* data: is binary memory to hash
unsigned long len: is bytes in data
unsigned char* out: receives 32 byte binary digest

@return

int: 0 on success (always successful)

@see libc/str/blake2.c

BLAKE2B256_Final

@param

struct ctx* b2b
unsigned char* out

@return

int

@see libc/str/blake2.c

BLAKE2B256_Init

@param

struct ctx* b2b

@return

int

@see libc/str/blake2.c

BLAKE2B256_Process

@param

struct ctx* b2b
const unsigned long* data

@return

int

@see libc/str/blake2.c

BLAKE2B256_Update

@param

struct ctx* b2b
void* in_data
unsigned long len

@return

int

@see libc/str/blake2.c

brk

Sets end of data section.

Your program break starts right after end of .bss as defined by the external linker-defined variable end. Setting it to a higher address will allocate more memory. After using this you may dealocate memory by specifying it back to a lower address.

The only virtue of brk(), and sbrk(), aside from compatibility with legacy software, is it's tinier than mmap() because since this API only supports Unix, we don't bother doing the complex memory interval tracking that mmap() does.

@param

void* neu: is the new end address of data segment, which shall be rounded automatically to a 4096-byte granularity

@return

int: 0 on success, or -1 w/ errno

@raise EINVAL if neu is less than the end of .bss

@raise EEXIST if expanded break would overlap existing mmap() memory

@raise ENOMEM if RLIMIT_DATA / RLIMIT_AS / RLIMIT_RSS is exceeded

@raise ENOSYS on Windows because WIN32 puts random stuff after your break

@threadsafe

@see libc/runtime/brk.c

brk_funlock

@return

void

@see libc/runtime/brk.c

brk_lock

@return

void

@see libc/runtime/brk.c

brk_unlock

@return

void

@see libc/runtime/brk.c

bsearch

Searches sorted array for exact item in logarithmic time.

@param

void* key
void* base
unsigned long nmemb
unsigned long size
int(*)() cmp

@return

void*

@see bsearch_r(), bisectcarleft()

@see libc/mem/bsearch.c

bsearch_r

Searches sorted array for exact item in logarithmic time.

@param

void* key
void* base
unsigned long nmemb
unsigned long size
int(*)() cmp
void* arg

@return

void*

@see bsearch(), bisectcarleft()

@see libc/mem/bsearch_r.c

_bsf

Returns position of first bit set.

                      ctz(𝑥)         31^clz(𝑥)   clz(𝑥)
  uint32 𝑥  _bsf(𝑥) tzcnt(𝑥)   ffs(𝑥)  _bsr(𝑥) lzcnt(𝑥)
0x00000000      wut       32        0      wut       32
0x00000001        0        0        1        0       31
0x80000001        0        0        1       31        0
0x80000000       31       31       32       31        0
0x00000010        4        4        5        4       27
0x08000010        4        4        5       27        4
0x08000000       27       27       28       27        4
0xffffffff        0        0        1       31        0

@param

int x: is a 32-bit integer

@return

int: number in range 0..31 or undefined if 𝑥 is 0

@see libc/intrin/bsf.c

_bsfl

Returns position of first bit set.

                      ctz(𝑥)         31^clz(𝑥)   clz(𝑥)
  uint32 𝑥  _bsf(𝑥) tzcnt(𝑥)   ffs(𝑥)  _bsr(𝑥) lzcnt(𝑥)
0x00000000      wut       32        0      wut       32
0x00000001        0        0        1        0       31
0x80000001        0        0        1       31        0
0x80000000       31       31       32       31        0
0x00000010        4        4        5        4       27
0x08000010        4        4        5       27        4
0x08000000       27       27       28       27        4
0xffffffff        0        0        1       31        0

@param

long x

@return

int: number in range 0..63 or undefined if 𝑥 is 0

@see libc/intrin/bsfl.c

_bsfll

Returns position of first bit set.

                      ctz(𝑥)         31^clz(𝑥)   clz(𝑥)
  uint32 𝑥  _bsf(𝑥) tzcnt(𝑥)   ffs(𝑥)  _bsr(𝑥) lzcnt(𝑥)
0x00000000      wut       32        0      wut       32
0x00000001        0        0        1        0       31
0x80000001        0        0        1       31        0
0x80000000       31       31       32       31        0
0x00000010        4        4        5        4       27
0x08000010        4        4        5       27        4
0x08000000       27       27       28       27        4
0xffffffff        0        0        1       31        0

@param

long x

@return

int: number in range 0..63 or undefined if 𝑥 is 0

@see libc/intrin/bsfll.c

_bsr

Returns binary logarithm of 𝑥.

                      ctz(𝑥)         31^clz(𝑥)   clz(𝑥)
  uint32 𝑥  _bsf(𝑥) tzcnt(𝑥)   ffs(𝑥)  _bsr(𝑥) lzcnt(𝑥)
0x00000000      wut       32        0      wut       32
0x00000001        0        0        1        0       31
0x80000001        0        0        1       31        0
0x80000000       31       31       32       31        0
0x00000010        4        4        5        4       27
0x08000010        4        4        5       27        4
0x08000000       27       27       28       27        4
0xffffffff        0        0        1       31        0

@param

int x: is a 32-bit integer

@return

int: number in range 0..31 or undefined if 𝑥 is 0

@see libc/intrin/bsr.c

_bsr128

Returns binary logarithm of integer 𝑥.

  uint32 𝑥  _bsf(𝑥) tzcnt(𝑥)   ffs(𝑥)   bsr(𝑥) lzcnt(𝑥)
0x00000000      wut       32        0      wut       32
0x00000001        0        0        1        0       31
0x80000001        0        0        1       31        0
0x80000000       31       31       32       31        0
0x00000010        4        4        5        4       27
0x08000010        4        4        5       27        4
0x08000000       27       27       28       27        4
0xffffffff        0        0        1       31        0

@param

rsi:rdi: is 128-bit unsigned 𝑥 value

@return

: eax number in range [0,128) or undef if 𝑥 is 0

@see also treasure trove of nearly identical functions

@see libc/intrin/bsr128.S

_bsrl

Returns binary logarithm of 𝑥.

                      ctz(𝑥)         31^clz(𝑥)   clz(𝑥)
  uint32 𝑥  _bsf(𝑥) tzcnt(𝑥)   ffs(𝑥)  _bsr(𝑥) lzcnt(𝑥)
0x00000000      wut       32        0      wut       32
0x00000001        0        0        1        0       31
0x80000001        0        0        1       31        0
0x80000000       31       31       32       31        0
0x00000010        4        4        5        4       27
0x08000010        4        4        5       27        4
0x08000000       27       27       28       27        4
0xffffffff        0        0        1       31        0

@param

long x: is a 64-bit integer

@return

int: number in range 0..63 or undefined if 𝑥 is 0

@see libc/intrin/bsrl.c

_bsrll

Returns binary logarithm of 𝑥.

                      ctz(𝑥)         31^clz(𝑥)   clz(𝑥)
  uint32 𝑥  _bsf(𝑥) tzcnt(𝑥)   ffs(𝑥)  _bsr(𝑥) lzcnt(𝑥)
0x00000000      wut       32        0      wut       32
0x00000001        0        0        1        0       31
0x80000001        0        0        1       31        0
0x80000000       31       31       32       31        0
0x00000010        4        4        5        4       27
0x08000010        4        4        5       27        4
0x08000000       27       27       28       27        4
0xffffffff        0        0        1       31        0

@param

long x: is a 64-bit integer

@return

int: number in range 0..63 or undefined if 𝑥 is 0

@see libc/intrin/bsrll.c

bswap_64

Byte-order conversion functions.

Endianness is deceptively complicated to the uninitiated. Many helpers have been written by our top minds to address perceived difficulties. These ones got through standardization processes. To protect their legacy, all 19 functions have been implemented in just 17 bytes.

@return

@see READ32LE(), READ32BE(), etc.

@asyncsignalsafe

@see libc/nexgen32e/lolendian.S

_bt

Shows backtrace if crash reporting facilities are linked.

@param

const char* fmt
...

@return

void

@see libc/intrin/bt.c

btowc

@param

int c

@return

unsigned int

@see libc/str/btowc.c

bzero

Sets memory to zero.

bzero n=0                          661 picoseconds
bzero n=1                          661 ps/byte          1,476 mb/s
bzero n=2                          330 ps/byte          2,952 mb/s
bzero n=3                          220 ps/byte          4,428 mb/s
bzero n=4                          165 ps/byte          5,904 mb/s
bzero n=7                           94 ps/byte         10,333 mb/s
bzero n=8                           41 ps/byte         23,618 mb/s
bzero n=15                          44 ps/byte         22,142 mb/s
bzero n=16                          20 ps/byte         47,236 mb/s
bzero n=31                          21 ps/byte         45,760 mb/s
bzero n=32                          20 ps/byte         47,236 mb/s
bzero n=63                          10 ps/byte         92,997 mb/s
bzero n=64                          15 ps/byte         62,982 mb/s
bzero n=127                         15 ps/byte         62,490 mb/s
bzero n=128                         10 ps/byte         94,473 mb/s
bzero n=255                         14 ps/byte         68,439 mb/s
bzero n=256                          9 ps/byte            105 gb/s
bzero n=511                         15 ps/byte         62,859 mb/s
bzero n=512                         11 ps/byte         83,976 mb/s
bzero n=1023                        15 ps/byte         61,636 mb/s
bzero n=1024                        10 ps/byte         88,916 mb/s
bzero n=2047                         9 ps/byte            105 gb/s
bzero n=2048                         8 ps/byte            109 gb/s
bzero n=4095                         8 ps/byte            115 gb/s
bzero n=4096                         8 ps/byte            118 gb/s
bzero n=8191                         7 ps/byte            129 gb/s
bzero n=8192                         7 ps/byte            130 gb/s
bzero n=16383                        6 ps/byte            136 gb/s
bzero n=16384                        6 ps/byte            137 gb/s
bzero n=32767                        6 ps/byte            140 gb/s
bzero n=32768                        6 ps/byte            141 gb/s
bzero n=65535                       15 ps/byte         64,257 mb/s
bzero n=65536                       15 ps/byte         64,279 mb/s
bzero n=131071                      15 ps/byte         63,166 mb/s
bzero n=131072                      15 ps/byte         63,115 mb/s
bzero n=262143                      15 ps/byte         62,052 mb/s
bzero n=262144                      15 ps/byte         62,097 mb/s
bzero n=524287                      15 ps/byte         61,699 mb/s
bzero n=524288                      15 ps/byte         61,674 mb/s
bzero n=1048575                     16 ps/byte         60,179 mb/s
bzero n=1048576                     15 ps/byte         61,330 mb/s
bzero n=2097151                     15 ps/byte         61,071 mb/s
bzero n=2097152                     15 ps/byte         61,065 mb/s
bzero n=4194303                     16 ps/byte         60,942 mb/s
bzero n=4194304                     16 ps/byte         60,947 mb/s
bzero n=8388607                     16 ps/byte         60,872 mb/s
bzero n=8388608                     16 ps/byte         60,879 mb/s

@param

void* p: is memory address
unsigned long n: is byte length

@return

void: p

@asyncsignalsafe

@see libc/intrin/bzero.c

c16rtomb

@param

char* s
unsigned short c16
unsigned int* ps

@return

unsigned long

@see libc/str/c16rtomb.c

c2rangr

Computes transcedental trigonometry op w/ reactive scaling.

@param

%rdx: points to op function
everything: else delegates

@return

@clob %ax

@see sin,cos,tan

@see libc/tinymath/c2rangr.S

c32rtomb

@param

char* s
unsigned int c
unsigned int* t

@return

unsigned long

@see libc/str/c32rtomb.c

calloc

Allocates n * itemsize bytes, initialized to zero.

@param

rdi: is number of items (n)
rsi: is size of each item (itemsize)

@return

: rax is memory address, or NULL w/ errno

@note overreliance on memalign is a sure way to fragment space

@see dlcalloc()

@threadsafe

@see libc/mem/calloc.S

CategorizeIp

Classifies IP address.

@param

unsigned int x

@return

int: integer e.g. kIpLoopback, kIpPrivate, etc.

@see GetIpCategoryName()

@see net/http/categorizeip.c

__cbrt

Returns cube root of 𝑥.

@param

double x

@return

double

@see libc/tinymath/cbrtc.c

cbrt

Returns cube root of 𝑥.

@param

%xmm0: holds binary64 number

@return

: %xmm0 holds binary64 result

@see libc/tinymath/cbrt.S

cbrtf

Returns cube root of 𝑥.

@param

%xmm0: holds binary32 number

@return

: %xmm0 holds binary32 result

@see libc/tinymath/cbrtf.S

cbrtl

Returns cube root of 𝑥.

@param

𝑥: is an 80-bit long double passed on stack in 16-bytes

@return

: result of computation on FPU stack in %st

@see libc/tinymath/cbrtl.S

ceil

Returns smallest integral not less than 𝑥.

@param

𝑥: is double scalar in low half of %xmm0

@return

: double scalar in low half of %xmm0

@see round(),rint(),nearbyint()

@see vroundsd $_MM_FROUND_TO_POS_INF|_MM_FROUND_NO_EXC,%xmm0,%xmm0,%xmm0

@see libc/tinymath/ceil.S

ceilf

Returns smallest integral not less than 𝑥.

@param

𝑥: is float scalar in low quarter of %xmm0

@return

: float scalar in low quarter of %xmm0

@see round(),rint(),nearbyint()

@see vroundss $_MM_FROUND_TO_POS_INF|_MM_FROUND_NO_EXC,%xmm0,%xmm0,%xmm0

@see libc/tinymath/ceilf.S

ceill

Returns smallest integral not less than 𝑥.

@param

𝑥: is long double passed on stack

@return

: long double in %st

@see libc/tinymath/ceill.S

_cescapec

Escapes byte for string literal.

This turns stuff like (char)0xFF into \0377. The returned string is word-encoded, e.g. '\\'|'0'<<010|'3'<<020|etc.

@param

dil: contains byte to escape

@return

@see libc/nexgen32e/cescapec.c

@see libc/nexgen32e/cescapec.S

cfgetispeed

Returns input baud rate.

@param

struct termios* t

@return

unsigned int

@asyncsignalsafe

@see libc/calls/cfspeed.c

cfgetospeed

Returns output baud rate.

@param

struct termios* t

@return

unsigned int

@asyncsignalsafe

@see libc/calls/cfspeed.c

cfmakeraw

@param

struct termios* t

@return

void

@see libc/calls/cfmakeraw.c

cfsetispeed

Sets input baud rate.

@param

struct termios* t
unsigned int speed

@return

int: 0 on success, or -1 w/ errno

@asyncsignalsafe

@see libc/calls/cfspeed.c

cfsetospeed

Sets output baud rate.

@param

struct termios* t
unsigned int speed

@return

int: 0 on success, or -1 w/ errno

@asyncsignalsafe

@see libc/calls/cfspeed.c

chdir

Sets current directory.

This does *not* update the PWD environment variable.

@param

const char* path

@return

int: 0 on success, or -1 w/ errno

@asyncsignalsafe

@see fchdir()

@see libc/calls/chdir.c

__check_fail

Handles failure of CHECK_xx() macros.

@param

const char* suffix
const char* opstr
unsigned long want
const char* wantstr
unsigned long got
const char* gotstr
const char* file
int line
const char* fmt
...

@return

void

@see libc/log/checkfail.c

__check_fail_ndebug

Handles failure of CHECK_xx() macros in -DNDEBUG mode.

This handler (1) makes binaries smaller by not embedding source code; and therefore (2) less likely to leak sensitive information. This can still print backtraces with function names if the .com.dbg file is in the same folder.

@param

unsigned long want
unsigned long got
const char* file
int line
const char* opchar
const char* fmt
...

@noreturn

@see libc/log/thunks/__check_fail_ndebug.S

@see libc/log/checkfail_ndebug.c

_check_sigchld

Checks to see if SIGCHLD should be raised on Windows.

@return

void: true if a signal was raised

@note yoinked by fork-nt.c

@see libc/calls/sigchld-nt.c

CheckElfAddress

@param

struct Elf64_Ehdr* elf
unsigned long mapsize
long addr
unsigned long addrsize

@return

void

@see libc/elf/checkelfaddress.c

CheckForMemoryLeaks

Tests for memory leaks.

This function needs to call __cxa_finalize(). Therefore any runtime services that depend on malloc() cannot be used, after calling this function.

@return

void

@see libc/log/leaks.c

chmod

Changes permissions on file, e.g.:

CHECK_NE(-1, chmod("foo/bar.txt", 0644));
CHECK_NE(-1, chmod("o/default/program.com", 0755));
CHECK_NE(-1, chmod("privatefolder/", 0700));

The esoteric bits generally available on System Five are:

CHECK_NE(-1, chmod("/opt/", 01000));          // sticky bit
CHECK_NE(-1, chmod("/usr/bin/sudo", 04755));  // setuid bit
CHECK_NE(-1, chmod("/usr/bin/wall", 02755));  // setgid bit

@param

const char* pathname: must exist
unsigned int mode: contains octal flags (base 8)

@return

int

@errors ENOENT, ENOTDIR, ENOSYS

@asyncsignalsafe

@see fchmod()

@see libc/calls/chmod.c

_chomp

Mutates line to remove line-ending characters.

@param

char* line: is NULL-propagating

@return

char*

@see getline

@see libc/str/chomp.c

_chomp16

Mutates line to remove line-ending characters.

@param

unsigned short* line: is NULL-propagating

@return

unsigned short*

@see getline

@see libc/str/chomp16.c

chown

Changes owner and/or group of pathname.

@param

const char* pathname
unsigned int uid: is user id, or -1u to not change
unsigned int gid: is group id, or -1u to not change

@return

int: 0 on success, or -1 w/ errno

@see fchown() if pathname is already open()'d

@see lchown() which does not dereference symbolic links

@see /etc/passwd for user ids

@see /etc/group for group ids

@asyncsignalsafe

@see libc/calls/chown.c

chroot

Changes root directory.

Please consider using unveil() instead of chroot(). If you use this system call then consider using both chdir() and closefrom() before calling this function. Otherwise there's a small risk that fchdir() could be used to escape the chroot() environment. Cosmopolitan Libc focuses on static binaries which make chroot() infinitely easier to use since you don't need to construct an entire userspace each time however unveil() is still better to use on modern Linux and OpenBSD because it doesn't require root privileges.

@param

const char* path: shall become the new root directory

@return

int: 0 on success, or -1 w/ errno

@raise EACCES if we don't have permission to search a component of path

@raise ENOTDIR if a directory component in path exists as non-directory

@raise ENAMETOOLONG if symlink-resolved path length exceeds PATH_MAX

@raise ENAMETOOLONG if component in path exists longer than NAME_MAX

@raise EPERM if not root or pledge() is in play

@raise EIO if a low-level i/o error occurred

@raise EFAULT if path is bad memory

@raise ENOENT if path doesn't exist

@raise ENOSYS on Windows

@see libc/calls/chroot.c

_classifypath

Classifies file path name.

For the purposes of this function, we always consider backslash interchangeable with forward slash, even though the underlying operating system might not. Therefore, for the sake of clarity, remaining documentation will only use the forward slash.

This function behaves the same on all platforms. For instance, this function will categorize C:/FOO.BAR as a DOS path, even if you're running on UNIX rather than DOS.

If you wish to check if a pathname is absolute, in a manner that's inclusive of DOS drive paths, DOS rooted paths, in addition to the New Technology UNC paths, then you may do the following:

if (_classifypath(str) & _kPathAbs) { ... }

To check if path is a relative path:

if (~_classifypath(str) & _kPathAbs) { ... }

Please note the above check includes rooted paths such as \foo which is considered absolute by MSDN and we consider it absolute although, it's technically relative to the current drive letter.

Please note that /foo/bar is an absolute path on Windows, even though it's actually a rooted path that's considered relative to current drive by WIN32.

@param

const char* s

@return

int

integer value that's one of following:

0 if non-weird relative path e.g. c
_kPathAbs if absolute (or rooted dos) path e.g. /⋯
_kPathDos if c:, d:foo i.e. drive-relative path
_kPathAbs|_kPathDos if proper dos path e.g. c:/foo
_kPathDos|_kPathDev if dos device path e.g. nul, conin$
_kPathAbs|_kPathWin if //c, //?c, etc.
_kPathAbs|_kPathWin|_kPathDev if //./⋯, //?/⋯
_kPathAbs|_kPathWin|_kPathDev|_kPathRoot if //. or //?
_kPathAbs|_kPathNt e.g. \??\\⋯ (undoc. strict backslash)

@see "The Definitive Guide on Win32 to NT Path Conversion", James Forshaw, Google Project Zero Blog, 2016-02-29

@see "Naming Files, Paths, and Namespaces", MSDN 01/04/2021

@see libc/str/classifypath.c

clearenv

Removes all environment variables.

@return

int: 0 on success, or nonzero on error

@see libc/intrin/clearenv.c

clearerr

Clears eof and error state indicators on stream.

@param

struct FILE* f: is file object stream pointer

@return

void

@see clearerr_unlocked()

@threadsafe

@see libc/stdio/clearerr.c

clearerr_unlocked

Clears eof and error state indicators on stream.

@param

struct FILE* f: is file object stream pointer

@return

void

@see clearerr()

@threadsafe

@see libc/stdio/clearerr_unlocked.c

__clk_tck

Returns system clock ticks per second.

The returned value is memoized. This function is intended to be used via the CLK_TCK macro wrapper.

The returned value is always greater than zero. It's usually 100 hertz which means each clock tick is 10 milliseconds long.

@return

int

@see libc/runtime/clktck.c

clock

Returns sum of CPU time consumed by current process since birth.

This function provides a basic idea of how computationally expensive your program is, in terms of both the userspace and kernel processor resources it's hitherto consumed. Here's an example of how you might display this information:

printf("consumed %g seconds of cpu time\n",
       (double)clock() / CLOCKS_PER_SEC);

This function offers at best microsecond accuracy on all supported platforms. Please note the reported values might be a bit chunkier depending on the kernel scheduler sampling interval see CLK_TCK.

@return

long: units of CPU time consumed, where each unit's time length should be 1./CLOCKS_PER_SEC seconds; Cosmopolitan currently returns the unit count in microseconds, i.e. CLOCKS_PER_SEC is hard-coded as 1000000. On failure this returns -1 / errno.

@raise ENOSYS should be returned currently if run on Bare Metal

@see clock_gettime() which polyfills this on Linux and BSDs

@see getrusage() which polyfills this on XNU and NT

@see libc/calls/clock.c

clock_getres

Returns granularity of clock.

@param

int clock
ANONYMOUS-STRUCT* ts

@return

int: 0 on success, or -1 w/ errno

@error EPERM if pledge() is in play without stdio promise

@error EINVAL if clock isn't supported on this system

@error EFAULT if ts points to bad memory

@threadsafe

@see libc/calls/clock_getres.c

clock_gettime

Returns nanosecond time.

This is a high-precision timer that supports multiple definitions of time. Among the more popular is CLOCK_MONOTONIC. This function has a zero syscall implementation of that on modern x86.

nowl                l:        45𝑐        15𝑛𝑠
rdtsc               l:        13𝑐         4𝑛𝑠
gettimeofday        l:        44𝑐        14𝑛𝑠
clock_gettime       l:        40𝑐        13𝑛𝑠
__clock_gettime     l:        35𝑐        11𝑛𝑠
sys_clock_gettime   l:       220𝑐        71𝑛𝑠

@param

int clock: can be one of: - CLOCK_REALTIME: universally supported - CLOCK_REALTIME_FAST: ditto but faster on freebsd - CLOCK_REALTIME_PRECISE: ditto but better on freebsd - CLOCK_REALTIME_COARSE: : like CLOCK_REALTIME_FAST w/ Linux 2.6.32+ - CLOCK_MONOTONIC: universally supported - CLOCK_MONOTONIC_FAST: ditto but faster on freebsd - CLOCK_MONOTONIC_PRECISE: ditto but better on freebsd - CLOCK_MONOTONIC_COARSE: : like CLOCK_MONOTONIC_FAST w/ Linux 2.6.32+ - CLOCK_MONOTONIC_RAW: is actually monotonic but needs Linux 2.6.28+ - CLOCK_PROCESS_CPUTIME_ID: linux and bsd - CLOCK_THREAD_CPUTIME_ID: linux and bsd - CLOCK_MONOTONIC_COARSE: linux, freebsd - CLOCK_PROF: linux and netbsd - CLOCK_BOOTTIME: linux and openbsd - CLOCK_REALTIME_ALARM: linux-only - CLOCK_BOOTTIME_ALARM: linux-only - CLOCK_TAI: linux-only
ANONYMOUS-STRUCT* ts: is where the result is stored

@return

int: 0 on success, or -1 w/ errno

@error EPERM if pledge() is in play without stdio promise

@error EINVAL if clock isn't supported on this system

@error EFAULT if ts points to bad memory

@see strftime(), gettimeofday()

@asyncsignalsafe

@threadsafe

@vforksafe

@see libc/calls/clock_gettime.c

__clock_gettime_get

Returns pointer to fastest clock_gettime().

@param

_Bool* opt_out_isfast

@return

int(*)()

@see libc/calls/clock_gettime.c

clock_nanosleep

Sleeps for particular amount of time.

Here's how you could sleep for one second:

clock_nanosleep(0, 0, &(struct timespec){1}, 0);

Your sleep will be interrupted automatically if you do something like press ctrl-c during the wait. That's an EINTR error and it lets you immediately react to status changes. This is always the case, even if you're using SA_RESTART since this is a @norestart system call.

void OnCtrlC(int sig) {} // EINTR only happens after delivery
signal(SIGINT, OnCtrlC); // do delivery rather than kill proc
printf("save me from sleeping forever by pressing ctrl-c\n");
clock_nanosleep(0, 0, &(struct timespec){INT_MAX}, 0);
printf("you're my hero\n");

If you want to perform an uninterruptible sleep without having to use sigprocmask() to block all signals then this function provides a good solution to that problem. For example:

struct timespec rel, now, abs;
clock_gettime(CLOCK_REALTIME, &now);
rel = timespec_frommillis(100);
abs = timespec_add(now, rel);
while (clock_nanosleep(CLOCK_REALTIME, TIMER_ABSTIME, &abs, 0));

will accurately spin on EINTR errors. That way you're not impeding signal delivery and you're not loosing precision on the wait timeout. This function has first-class support on Linux, FreeBSD, and NetBSD; on OpenBSD it's good; on XNU it's bad; and on Windows it's ugly.

@param

int clock: should be CLOCK_REALTIME and you may consult the docs of your preferred platforms to see what other clocks might work
int flags: can be 0 for relative and TIMER_ABSTIME for absolute
struct now* req: can be a relative or absolute time, depending on flags
struct now* rem: shall be updated with the remainder of unslept time when (1) it's non-null; (2) flags is 0; and (3) -1 w/ EINTR is returned; if this function returns 0 then rem is undefined; if flags is TIMER_ABSTIME then rem is ignored

@return

int: 0 on success, or errno on error

@raise EINTR when a signal got delivered while we were waiting

@raise ECANCELED if thread was cancelled in masked mode

@raise ENOTSUP if clock is known but we can't use it here

@raise EFAULT if req or null or bad memory was passed

@raise EINVAL if clock is unknown to current platform

@raise EINVAL if flags has an unrecognized value

@raise EINVAL if req->tv_nsec ∉ [0,1000000000)

@raise ENOSYS on bare metal

@cancellationpoint

@returnserrno

@norestart

@see libc/calls/clock_nanosleep.c

clone

Creates thread without malloc being linked.

If you use clone() you're on you're own, e.g.

int worker(void *arg) { return 0; }
struct CosmoTib tib = {.tib_self = &tib, .tib_tid = -1};
atomic_int tid;
char *stk = _mapstack();
clone(worker, stk, GetStackSize() - 16,
      CLONE_VM | CLONE_THREAD | CLONE_FS | CLONE_FILES |
      CLONE_SIGHAND | CLONE_PARENT_SETTID | CLONE_CHILD_SETTID |
      CLONE_CHILD_CLEARTID | CLONE_SETTLS,
      arg, &tid, &tib, &tib.tib_tid);
while (atomic_load(&tid) == 0) sched_yield();
// thread is known
while (atomic_load(&tib.tib_tid) < 0) sched_yield();
// thread is running
while (atomic_load(&tib.tib_tid) > 0) sched_yield();
// thread has terminated
_freestack(stk);

Threads are created in a detached manner. They currently can't be synchronized using wait() or posix signals. Threads created by this function should be synchronized using shared memory operations.

Any memory that's required by this system call wrapper is allocated to the top of your stack. This shouldn't be more than 128 bytes.

Your function is called from within the stack you specify. A return address is pushed onto your stack, that causes returning to jump to _Exit1() which terminates the thread. Even though the callback says it supports a return code, that'll only work on Linux and Windows.

This function follows the same ABI convention as the Linux userspace libraries, with a few small changes. The varargs has been removed to help prevent broken code, and the stack size and tls size parameters are introduced for compatibility with FreeBSD.

To keep this system call lightweight, only the thread creation use case is polyfilled across platforms. For example, if you want fork that works on OpenBSD for example, don't do it with clone(SIGCHLD) and please just call fork(). Even if you do that on Linux, it will effectively work around libc features like atfork(), so that means other calls like getpid() may return incorrect values.

@param

void* func

is your callback function, which this wrapper requires not be null, otherwise EINVAL is raised. It is passed two args within the child thread: (1) the caller-supplied arg and (2) the new tid is always passed in the second arg for convenience

void* stk

points to the bottom of a caller allocated stack, which must be allocated via mmap() using the MAP_STACK flag, or else you won't get optimal performance and it won't work on OpenBSD

unsigned long stksz

is the size of that stack in bytes, we recommend that that this be set to GetStackSize() or else memory safety tools like kprintf() can't do as good and quick of a job; this value must be 16-aligned plus it must be at least 4192 bytes in size and it's advised to have the bottom-most page, be a guard page

int flags

which SHOULD always have all of these flags:

CLONE_THREAD
CLONE_VM
CLONE_FS
CLONE_FILES
CLONE_SIGHAND

This system call wrapper is intended for threads, and as such, we won't polyfill Linux's ability to simulate unrelated calls (e.g. fork, vfork) via clone() on other platforms. Please just call fork() and vfork() when that's what you want.

Your flags may also optionally also additionally bitwise-OR any combination of the following additional flags:

CLONE_CHILD_SETTID must be specified if you intend to set the ctid argument, which will updated with the child tid once the child has started.
CLONE_PARENT_SETTID must be specified if you intend to set the ptid argument, which is updated at the most opportune moment. On all platforms except XNU, this happens before clone() returns. On XNU, it happens once the thread starts.
CLONE_CHILD_CLEARTID causes *ctid = 0 upon child thread termination. This is used to implement join so that the parent may know when it's safe to free the child's stack memory, and as such, is guaranteed to happen AFTER the child thread has either terminated or has finished using its stack memory
CLONE_SETTLS is needed if you intend to specify the tls argument, which after thread creation may be accessed using __get_tls(). Doing this means that errno, gettid(), etc. correctly work. Caveat emptor if you choose not to do this.

void* arg

is passed as an argument to func in the child thread

void* ptid

void* tls

may be used to set the thread local storage segment; this parameter is ignored if CLONE_SETTLS is not set

void* ctid

lets the child receive its thread id without having to call gettid() and is ignored if CLONE_CHILD_SETTID isn't set

@return

int: 0 on success, or errno on errno

@threadsafe

@see libc/runtime/clone.c

close

Closes file descriptor.

This function releases resources returned by functions such as:

openat()
socket()
accept()
epoll_create()
landlock_create_ruleset()

This function should never be reattempted if an error is returned; however, that doesn't mean the error should be ignored. This goes against the conventional wisdom of looping on EINTR.

@param

int fd

@return

int: 0 on success, or -1 w/ errno

@raise EINTR if signal was delivered; do *not* retry

@raise EBADF if fd is negative or not open; however, an exception is made by Cosmopolitan Libc for close(-1) which returns zero and does nothing, in order to assist with code that may wish to close the same resource multiple times without dirtying errno

@raise EIO if a low-level i/o error occurred

@asyncsignalsafe

@vforksafe

@see libc/calls/close.c

close_range

Closes inclusive range of file descriptors, e.g.

// close all non-stdio file descriptors
if (close_range(3, -1, 0) == -1) {
  for (int i = 3; i < 256; ++i) {
    close(i);
  }
}

The following flags are available:

CLOSE_RANGE_UNSHARE (Linux-only)
CLOSE_RANGE_CLOEXEC (Linux-only)

This is only supported on Linux 5.9+ and FreeBSD 13+. Consider using closefrom() which will work on OpenBSD too.

@param

unsigned int first
unsigned int last
unsigned int flags

@return

int: 0 on success, or -1 w/ errno

@error EINVAL if flags are bad or first is greater than last

@error EMFILE if a weird race condition happens on Linux

@error ENOSYS if not Linux 5.9+ or FreeBSD 13+

@error ENOMEM on Linux maybe

@see closefrom()

@see libc/calls/close_range.c

closedir

Closes directory object returned by opendir().

@param

struct dirstream* dir

@return

int: 0 on success or -1 w/ errno

@see libc/stdio/dirstream.c

closefrom

Closes extra file descriptors, e.g.

if (closefrom(3))
  for (int i = 3; i < 256; ++i)
    close(i);

@param

int first

@return

int: 0 on success, or -1 w/ errno

@raise EBADF if first is negative

@raise ENOSYS if not Linux 5.9+, FreeBSD 8+, OpenBSD, or NetBSD

@raise EBADF on OpenBSD if first is greater than highest fd

@raise EINVAL if flags are bad or first is greater than last

@raise EMFILE if a weird race condition happens on Linux

@raise ECANCELED if thread was cancelled in masked mode

@raise EINTR possibly on OpenBSD

@raise ENOMEM on Linux maybe

@see libc/calls/closefrom.c

CloseHandle

Closes an open object handle.

@param

long hObject

@return

int

@note this wrapper takes care of ABI, STRACE(), and __winerr()

@see libc/intrin/closehandle.c

closelog

Closes the file descriptor being used to write to the system logger

Use of closelog is optional

@return

void

@asyncsignalsafe

@see libc/sock/syslog.c

CloseSymbolTable

Frees symbol table.

@param

struct SymbolTable** table

@return

int: 0 on success or -1 on system error

@see libc/runtime/closesymboltable.c

commandv

Resolves full pathname of executable.

@param

const char* name
char* pathbuf
unsigned long pathbufsz

@return

char*: execve()'able path, or NULL w/ errno

@errno ENOENT, EACCES, ENOMEM

@see free(), execvpe()

@asyncsignalsafe

@vforksafe

@see libc/calls/commandv.c

commandvenv

Finds full executable path in overridable way.

This is a higher level version of the commandv() function. Programs that spawn subprocesses can use this function to determine the path at startup. Here's an example how you could use it:

if ((strace = commandvenv("STRACE", "strace"))) {
  strace = strdup(strace);
} else {
  fprintf(stderr, "error: please install strace\n");
  exit(1);
}

@param

const char* var: is environment variable which may be used to override PATH search, and it can force a NULL result if it's empty
const char* cmd: is name of program, which is returned asap if it's an absolute path

@return

const char*: pointer to exe path string, or NULL if it couldn't be found or the environment variable was empty; noting that the caller should copy this string before saving it

@see libc/log/commandvenv.c

CompareDnsNames

Compares DNS hostnames in reverse lexicographical asciibetical order.

@param

const char* A
const char* B

@return

int: <0, 0, or >0

@see test/libc/dns/comparednsnames_test.c (the code that matters)

@see libc/dns/comparednsnames.c

CompareSlices

@param

const char* a
unsigned long n
const char* b
unsigned long m

@return

int

@see libc/str/compareslices.c

CompareSlicesCase

@param

const char* a
unsigned long n
const char* b
unsigned long m

@return

int

@see libc/str/compareslicescase.c

compress

Compresses source buffer into the destination buffer. sourceLen is the byte length of the source buffer. Upon entry, destLen is the total size of the destination buffer, which must be at least the value returned by compressBound(sourceLen). Upon exit, destLen is the actual size of the compressed data. compress() is equivalent to compress2() with a level parameter of Z_DEFAULT_COMPRESSION.

@return

int: Z_OK if success, Z_MEM_ERROR if there was not enough memory, Z_BUF_ERROR if there was not enough room in the output buffer.

@see third_party/zlib/zlib.h

compress2

Compresses source buffer into the destination buffer. The level parameter has the same meaning as in deflateInit. sourceLen is the byte length of the source buffer. Upon entry, destLen is the total size of the destination buffer, which must be at least the value returned by compressBound(sourceLen). Upon exit, destLen is the actual size of the compressed data.

@return

int: Z_OK if success, Z_MEM_ERROR if there was not enough memory, Z_BUF_ERROR if there was not enough room in the output buffer, Z_STREAM_ERROR if the level parameter is invalid.

@see third_party/zlib/zlib.h

compressBound

Returns an upper bound on the compressed size after compress() or compress2() on sourceLen bytes. It would be used before a compress() or compress2() call to allocate the destination buffer.

@return

unsigned long

@see third_party/zlib/zlib.h

connect

Connects socket to remote end.

ProTip: Connectionless sockets, e.g. UDP, can be connected too. The benefit is not needing to specify the remote address on each send. It also means getsockname() can be called to retrieve routing details.

@param

int fd
struct sa* addr
unsigned int addrsize

@return

int: 0 on success or -1 w/ errno

@cancellationpoint

@asyncsignalsafe

@restartable (unless SO_RCVTIMEO)

@see libc/sock/connect.c

ContainsInt

@param

struct SortedInts* t
int k

@return

_Bool

@see libc/mem/sortedints.c

ConvertTicksToNanos

@param

unsigned long ticks

@return

long double

@see libc/calls/oldbench.c

copy_file_range

Transfers data between files.

If this system call is available (Linux c. 2018 or FreeBSD c. 2021) and the file system supports it (e.g. ext4) and the source and dest files are on the same file system, then this system call shall make copies go about 2x faster.

This implementation requires Linux 5.9+ even though the system call was introduced in Linux 4.5. That's to ensure ENOSYS works reliably due to a faulty backport, that happened in RHEL7. FreeBSD detection on the other hand will work fine.

@param

int infd: is source file, which should be on same file system
long* opt_in_out_inoffset: may be specified for pread() behavior
int outfd: should be a writable file, but not O_APPEND
long* opt_in_out_outoffset: may be specified for pwrite() behavior
unsigned long uptobytes: is maximum number of bytes to transfer
unsigned int flags: is reserved for future use and must be zero

@return

long: number of bytes transferred, or -1 w/ errno

@raise EXDEV if source and destination are on different filesystems

@raise EBADF if infd or outfd aren't open files or append-only

@raise EPERM if fdout refers to an immutable file on Linux

@raise ENOTSUP if infd or outfd is a zip file descriptor

@raise ECANCELED if thread was cancelled in masked mode

@raise EINVAL if ranges overlap or flags is non-zero

@raise EFBIG if setrlimit(RLIMIT_FSIZE) is exceeded

@raise EFAULT if one of the pointers memory is bad

@raise ERANGE if overflow happens computing ranges

@raise ENOSPC if file system has run out of space

@raise ETXTBSY if source or dest is a swap file

@raise EINTR if a signal was delivered instead

@raise EISDIR if source or dest is a directory

@raise ENOSYS if not Linux 5.9+ or FreeBSD 13+

@raise EIO if a low-level i/o error happens

@see sendfile() for seekable → socket

@see splice() for fd ↔ pipe

@cancellationpoint

@see libc/calls/copy_file_range.c

_copyfd

Copies data between fds the old fashioned way.

@param

int infd
int outfd
unsigned long n

@return

long: bytes successfully exchanged

@see libc/mem/copyfd.c

_copyfile

Copies file.

This implementation goes 2x faster than the cp command that comes included with most systems since we use the newer copy_file_range() system call rather than sendfile().

@param

const char* src
const char* dst
int flags: may have COPYFILE_PRESERVE_TIMESTAMPS, COPYFILE_NOCLOBBER

@return

int: 0 on success, or -1 w/ errno

@see libc/calls/copyfile.c

copysign

Returns 𝑥 with same sign as 𝑦.

@param

𝑥: is double scalar in low half of %xmm0
𝑦: is double scalar in low half of %xmm1

@return

: double scalar in low half of %xmm0

@see libc/tinymath/copysign.S

copysignf

Returns 𝑥 with same sign as 𝑦.

@param

𝑦: is float scalar in low quarter of %xmm0
𝑥: is float scalar in low quarter of %xmm1

@return

: float scalar in low quarter of %xmm0

@see libc/tinymath/copysignf.S

copysignl

Returns 𝑥 with same sign as 𝑦.

@param

𝑥: is an 80-bit long double passed on stack in 16-bytes
𝑦: is the power, also pushed on stack, in reverse order

@return

: result on FPU stack in %st

@see libc/tinymath/copysignl.S

cos

Returns cosine of 𝑥.

@param

double x

@return

double

@note should take ~5ns

@see libc/tinymath/cos.c

cosh

Returns hyperbolic cosine of 𝑥.

cosh(x) = (exp(x) + 1/exp(x))/2
        = 1 + 0.5*(exp(x)-1)*(exp(x)-1)/exp(x)
        = 1 + x*x/2 + o(x^4)

@param

double x

@return

double

@see libc/tinymath/cosh.c

coshf

Returns hyperbolic cosine of 𝑥.

cosh(x) = (exp(x) + 1/exp(x))/2
        = 1 + 0.5*(exp(x)-1)*(exp(x)-1)/exp(x)
        = 1 + x*x/2 + o(x^4)

@param

float x

@return

float

@see libc/tinymath/coshf.c

coshl

Returns hyperbolic cosine of 𝑥.

cosh(x) = (exp(x) + 1/exp(x))/2
        = 1 + 0.5*(exp(x)-1)*(exp(x)-1)/exp(x)
        = 1 + x*x/2 + o(x^4)

@param

long double x

@return

long double

@see libc/tinymath/coshl.c

cosl

Returns cosine of 𝑥.

@param

𝑥: is an 80-bit long double passed on stack in 16-bytes

@return

: %st stores result

@domain -(3π/8) < 𝑥 < 3π/8 for best accuracy

@see libc/tinymath/cosl.S

cosmo

Cosmopolitan runtime.

@param

edi: is argc
rsi: is argv
rdx: is environ
rcx: is auxv

@noreturn

@see libc/runtime/cosmo.S

cosmo2flock

@param

unsigned long memory

@return

void

@see libc/calls/metaflock.c

_countbits

Returns population count of array.

@param

void* a: is byte sequence
unsigned long n

@return

unsigned long: number of bits set to one

@note 30gbps on Nehalem (Intel 2008+) otherwise 3gbps

@see libc/intrin/countbits.c

countbranch_report

@return

void

@see libc/log/countbranch_report.c

countexpr_report

@return

void

@see libc/log/countexpr_report.c

CountInt

@param

struct SortedInts* t
int k

@return

int

@see libc/mem/sortedints.c

CountTokens

Returns current number of tokens in bucket.

@param

_Atomic char* b: is array of token buckets
unsigned int x: is ipv4 address
int c: is cidr

@return

int

@see net/http/tokenbucket.c

cprojl

Projects into Rienmann sphere.

@param

z: is complex long double passed on stack

@return

@note needs sse3

@see libc/tinymath/cprojl.S

CPU_AND

@param

struct cpu_set_t* d
struct cpu_set_t* x
struct cpu_set_t* y

@return

void

@see libc/calls/CPU_AND.c

CPU_COUNT

@param

struct cpu_set_t* set

@return

int

@see libc/calls/CPU_COUNT.c

CPU_EQUAL

@param

struct cpu_set_t* x
struct cpu_set_t* y

@return

int

@see libc/calls/CPU_EQUAL.c

CPU_OR

@param

struct cpu_set_t* d
struct cpu_set_t* x
struct cpu_set_t* y

@return

void

@see libc/calls/CPU_OR.c

CPU_XOR

@param

struct cpu_set_t* d
struct cpu_set_t* x
struct cpu_set_t* y

@return

void

@see libc/calls/CPU_XOR.c

CPU_ZERO

@param

struct cpu_set_t* set

@return

void

@see libc/calls/CPU_ZERO.c

crc32

Update a running CRC-32 with the bytes buf[0..len-1] and return the updated CRC-32. If buf is Z_NULL, this function returns the required initial value for the crc. Pre- and post-conditioning (one's complement) is performed within this function so it shouldn't be done by the application.

Usage example:

uLong crc = crc32(0L, Z_NULL, 0);
while (read_buffer(buffer, length) != EOF) {
  crc = crc32(crc, buffer, length);
}
if (crc != original_crc) error();

@return

unsigned long

@see third_party/zlib/zlib.h

crc32_combine

Combine two CRC-32 check values into one. For two sequences of bytes, seq1 and seq2 with lengths len1 and len2, CRC-32 check values were calculated for each, crc1 and crc2. crc32_combine() returns the CRC-32 check value of seq1 and seq2 concatenated, requiring only crc1, crc2, and len2.

@return

unsigned long

@see third_party/zlib/zlib.h

crc32_pclmul

Computes Phil Katz CRC-32 w/ carryless multiply isa.

This is support code that's abstracted by crc32_z().

@param

edi: is initial value
rsi: points to buffer
rdx: is bytes in buffer that's >=64 and %16==0

@return

: eax is crc32

@note needs Westmere (c.2010) or Bulldozer (c.2011)

@see “Fast CRC Computation for Generic Polynomials Using PCLMULQDQ Instruction” V. Gopal, E. Ozturk, et al., 2009, intel.ly/2ySEwL0

@see libc/nexgen32e/crc32-pclmul.S

crc32_z

Computes Phil Katz CRC-32 used by zip/zlib/gzip/etc.

x^32+x^26+x^23+x^22+x^16+x^12+x^11+x^10+x^8+x^7+x^5+x^4+x^2+x+1
0b100000100110000010001110110110111
_bitreverse32(0x104c11db7)

This implementation takes 32 picoseconds per byte or 30 gibibyte/s.

@param

unsigned int h: is initial value
void* data
unsigned long size

@return

unsigned int

@see libc/str/crc32z.c

crc32c

Computes 32-bit Castagnoli Cyclic Redundancy Check.

@param

unsigned int init: is the initial hash value
void* data: points to the data
unsigned long size: is the byte size of data

@return

unsigned int: eax is the new hash value

@note Used by ISCSI, TensorFlow, etc.

@see libc/str/crc32c.c

crc32init

Generates lookup table for computing CRC-32 byte-by-byte.

void crc32init(uint32_t table[256], uint32_t polynomial) {
  uint32_t d, i, r;
  for (d = 0; d < 256; ++d) {
    r = d;
    for (i = 0; i < 8; ++i) {
      r = r >> 1 ^ (r & 1 ? polynomial : 0);
    }
    table[d] = r;
  }
}

@param

rdi: is pointer to uint32_t[256] array
esi: 32-bit binary polynomial config

@return

@note imposes ~300ns one-time cost

@see libc/nexgen32e/crc32init.S

creat

Creates file.

This is equivalent to saying:

int fd = openat(AT_FDCWD, file, O_CREAT | O_WRONLY | O_TRUNC, mode);

@param

const char* file: specifies filesystem path to create
unsigned int mode: is octal bits, e.g. 0644 usually

@return

int: file descriptor, or -1 w/ errno

@see openat() for further documentation

@cancellationpoint

@asyncsignalsafe

@restartable

@threadsafe

@vforksafe

@see libc/calls/creat.c

CreateDirectory

Creates directory on the New Technology.

@param

const unsigned short* lpPathName
struct NtSecurityAttributes* lpSecurityAttributes

@return

int: handle, or -1 on failure

@note this wrapper takes care of ABI, STRACE(), and __winerr()

@see libc/intrin/createdirectory.c

CreateFile

Opens file on the New Technology.

@param

const unsigned short* lpFileName
unsigned int dwDesiredAccess
unsigned int dwShareMode
struct NtSecurityAttributes* opt_lpSecurityAttributes
int dwCreationDisposition
unsigned int dwFlagsAndAttributes
long opt_hTemplateFile

@return

long: handle, or -1 on failure

@note this wrapper takes care of ABI, STRACE(), and __winerr()

@see libc/intrin/createfile.c

CreateFileMapping

Creates file mapping object on the New Technology.

@param

long opt_hFile: may be -1 for MAP_ANONYMOUS behavior
struct NtSecurityAttributes* opt_lpFileMappingAttributes
unsigned int flProtect
unsigned int dwMaximumSizeHigh
unsigned int dwMaximumSizeLow
const unsigned short* opt_lpName

@return

long: handle, or 0 on failure

@note this wrapper takes care of ABI, STRACE(), and __winerr()

@see MapViewOfFileEx()

@see libc/intrin/createfilemapping.c

CreateFileMappingNuma

Creates file mapping object on the New Technology.

@param

long opt_hFile: may be -1 for MAP_ANONYMOUS behavior
struct NtSecurityAttributes* opt_lpFileMappingAttributes
unsigned int flProtect
unsigned int dwMaximumSizeHigh
unsigned int dwMaximumSizeLow
const unsigned short* opt_lpName
unsigned int nndDesiredNumaNode

@return

long: handle, or 0 on failure

@note this wrapper takes care of ABI, STRACE(), and __winerr()

@see MapViewOfFileExNuma()

@see libc/intrin/createfilemappingnuma.c

CreateMemoryInterval

@param

struct _mmi* mm
int i

@return

int

@see libc/intrin/memtrack.greg.c

CreateNamedPipe

Creates pipe.

@param

const unsigned short* lpName
unsigned int dwOpenMode
unsigned int dwPipeMode
unsigned int nMaxInstances
unsigned int nOutBufferSize
unsigned int nInBufferSize
unsigned int nDefaultTimeOutMs
struct NtSecurityAttributes* opt_lpSecurityAttributes

@return

long: handle to server end

@note this wrapper takes care of ABI, STRACE(), and __winerr()

@see libc/intrin/createnamedpipe.c

CreatePipe

Creates anonymous pipe.

@param

long* out_hReadPipe
long* out_hWritePipe
struct NtSecurityAttributes* opt_lpPipeAttributes
unsigned int nSize

@return

int

@note this wrapper takes care of ABI, STRACE(), and __winerr()

@see libc/intrin/createpipe.c

CreatePipeName

@param

unsigned short* a

@return

unsigned short*

@see libc/calls/createpipename.c

CreateProcess

Creates process on the New Technology.

@param

const unsigned short* opt_lpApplicationName
unsigned short* lpCommandLine
struct NtSecurityAttributes* opt_lpProcessAttributes
struct NtSecurityAttributes* opt_lpThreadAttributes
int bInheritHandles
unsigned int dwCreationFlags
void* opt_lpEnvironment
const unsigned short* opt_lpCurrentDirectory
struct NtStartupInfo* lpStartupInfo
struct NtProcessInformation* opt_out_lpProcessInformation

@return

int

@note this wrapper takes care of ABI, STRACE(), and __winerr()

@see libc/intrin/createprocess.c

CreateSymbolicLink

Creates symbolic link on the New Technology.

@param

const unsigned short* lpSymlinkFileName
const unsigned short* lpTargetPathName
unsigned int dwFlags

@return

int

@note you need to elevate process privileges before calling this

@note this wrapper takes care of ABI, STRACE(), and __winerr()

@see libc/intrin/createsymboliclink.c

CreateThread

Opens file on the New Technology.

@param

struct NtSecurityAttributes* lpThreadAttributes
unsigned long dwStackSize: may be 0 for default per executable
unsigned int(*)() lpStartAddress
void* lpParameter
unsigned int dwCreationFlags
unsigned int* opt_lpThreadId

@return

long: thread handle, or 0 on failure

@note this wrapper takes care of ABI, STRACE()

@see libc/intrin/createthread.c

critbit0_allprefixed

Invokes callback for all items with prefix.

@param

struct critbit0* t
const char* prefix
long(*)() callback
void* arg

@return

long: 0 unless iteration was halted by CALLBACK returning nonzero, in which case that value is returned

@note h/t djb and agl

@see libc/mem/critbit0_allprefixed.c

critbit0_clear

Removes all items from 𝑡.

@param

struct critbit0* t: tree

@return

void

@note h/t djb and agl

@see libc/mem/critbit0_clear.c

critbit0_contains

Returns non-zero iff 𝑢 ∈ 𝑡.

@param

struct critbit0* t: tree
const char* u: NUL-terminated string

@return

_Bool

@note h/t djb and agl

@see libc/mem/critbit0_contains.c

critbit0_delete

Removes 𝑢 from 𝑡.

@param

struct critbit0* t: tree
const char* u: NUL-terminated string

@return

_Bool: true if 𝑡 was mutated

@note h/t djb and agl

@see libc/mem/critbit0_delete.c

critbit0_emplace

Inserts 𝑢 into 𝑡 without copying.

@param

struct critbit0* t: is critical bit tree
char* u: is nul-terminated string which must be 8+ byte aligned and becomes owned by the tree afterwards
unsigned long ulen

@return

int: true if 𝑡 was mutated, or -1 w/ errno

@note h/t djb and agl

@see libc/mem/critbit0_emplace.c

critbit0_get

Returns first item in 𝑡 with prefix 𝑢.

@param

struct critbit0* t: tree
const char* u: NUL-terminated string

@return

char*: item or NULL if not found

@note h/t djb and agl

@see libc/mem/critbit0_get.c

critbit0_insert

Inserts 𝑢 into 𝑡.

@param

struct critbit0* t: tree
const char* u: NUL-terminated string

@return

int: true if 𝑡 was mutated, or -1 w/ errno

@note h/t djb and agl

@see libc/mem/critbit0_insert.c

crypt

Encrypts password the old fashioned way.

The method of encryption depends on the first three chars of salt:

$1$ is MD5
$2$ is Blowfish
$5$ is SHA-256
$6$ is SHA-512
Otherwise DES

@param

const char* key
const char* salt

@return

char*: static memory with encrypted password

@see third_party/argon2/

@see third_party/musl/crypt.c

crypt_r

Encrypts password the old fashioned way.

The method of encryption depends on the first three chars of salt:

$1$ is MD5
$2$ is Blowfish
$5$ is SHA-256
$6$ is SHA-512
Otherwise DES

@param

const char* key
const char* salt
struct crypt_data* data

@return

char*: static memory with encrypted password

@see third_party/argon2/

@see third_party/musl/crypt_r.c

ctermid

Generates path of controlling terminal.

This function always returns /dev/tty since that's supported by all supported platforms, and polyfilled on Windows.

@param

char* s: may optionally specify an outut buffer L_ctermid in size

@return

char*: pointer to s (or image memory if s was null) which contains path of controlling terminal, or empty string if if this program is a win32 app running in gui mode

@see libc/stdio/ctermid.c

ctime

@param

const long* timep

@return

char*

@see libc/time/ctime.c

ctime_r

@param

const long* timep
char* buf

@return

char*

@see libc/time/ctime_r.c

__cxa_atexit

Adds global destructor.

Destructors are called in reverse order. They won't be called if the program aborts or _exit() is called. Invocations of this function are usually generated by the C++ compiler. Behavior is limitless if some other module has linked calloc().

@param

void* fp: is void(*)(T)
void* arg: is passed to callback
void* pred: can be non-null for things like dso modules

@return

int: 0 on success or nonzero w/ errno

@note folks have forked libc in past just to unbloat atexit()

@see libc/intrin/cxaatexit.c

__cxa_finalize

Triggers global destructors.

They're called in LIFO order. If a destructor adds more destructors, then those destructors will be called immediately following, before iteration continues.

@param

void* pred: can be null to match all

@return

void

@see libc/intrin/cxafinalize.c

__cxa_printexits

Prints global destructors.

@param

struct FILE* f
void* pred: can be null to match all

@return

void

@see libc/log/cxaprintexits.c

_d2ld2

Thunks double(*fn)(double,double) -> long double fn.

@param

%xmm0[0]: contains double param

@return

: %xmm0[0] contains double result

@note 100% negligible overhead

@see libc/tinymath/d2ld2.S

daemon

Runs process in background.

On Unix this calls fork() and setsid(). On Windows this is implemented using CreateProcess(kNtDetachedProcess).

@param

int nochdir
int noclose

@return

int: 0 on success, or -1 w/ errno

@see libc/runtime/daemon.c

daylight

@type

int

@see libc/time/timezone.c

DecodeBase64

Decodes base64 ascii representation to binary.

This supports the following alphabets:

ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/
ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_

@param

const char* data: is input value
unsigned long size: if -1 implies strlen
unsigned long* out_size: if non-NULL receives output length

@return

char*: allocated NUL-terminated buffer, or NULL w/ errno

@see net/http/decodebase64.c

DecodeDosArgv

@param

int ignore
struct st_* st

@return

void

@see libc/runtime/getdosargv.c

DecodeLatin1

Decodes ISO-8859-1 to UTF-8.

@param

const char* p: is input value
unsigned long n: if -1 implies strlen
unsigned long* z: if non-NULL receives output length

@return

char*: allocated NUL-terminated buffer, or NULL w/ errno

@see net/http/decodelatin1.c

DecodeNf32

Decodes u32 from ANSI Nf sequence.

@param

const char* s
char** e

@return

unsigned int

@see libc/fmt/decodenf32.c

_defer

Calls fn(arg) when function returns.

This garbage collector overwrites the return address on the stack so that the RET instruction calls a trampoline which calls free(). It's loosely analogous to Go's defer keyword rather than a true cycle gc.

@param

void* fn
void* arg

@return

void*

@warning do not return a gc()'d pointer

@warning do not realloc() with gc()'d pointer

@warning be careful about static keyword due to impact of inlining

@note you should use -fno-omit-frame-pointer

@threadsafe

@see libc/mem/gc.c

deflate

deflate compresses as much data as possible, and stops when the input buffer becomes empty or the output buffer becomes full. It may introduce some output latency (reading input without producing any output) except when forced to flush.

The detailed semantics are as follows. deflate performs one or both of the following actions:

Compress more input starting at next_in and update next_in and

avail_in accordingly. If not all input can be processed (because there is not enough room in the output buffer), next_in and avail_in are updated and processing will resume at this point for the next call of deflate().

Generate more output starting at next_out and update next_out and

avail_out accordingly. This action is forced if the parameter flush is non zero. Forcing flush frequently degrades the compression ratio, so this parameter should be set only when necessary. Some output may be provided even if flush is zero.

Before the call of deflate(), the application should ensure that at least one of the actions is possible, by providing more input and/or consuming more output, and updating avail_in or avail_out accordingly; avail_out should never be zero before the call. The application can consume the compressed output when it wants, for example when the output buffer is full (avail_out == 0), or after each call of deflate(). If deflate returns Z_OK and with zero avail_out, it must be called again after making room in the output buffer because there might be more output pending. See deflatePending(), which can be used if desired to determine whether or not there is more ouput in that case.

Normally the parameter flush is set to Z_NO_FLUSH, which allows deflate to decide how much data to accumulate before producing output, in order to maximize compression.

If the parameter flush is set to Z_SYNC_FLUSH, all pending output is flushed to the output buffer and the output is aligned on a byte boundary, so that the decompressor can get all input data available so far. (In particular avail_in is zero after the call if enough output space has been provided before the call.) Flushing may degrade compression for some compression algorithms and so it should be used only when necessary. This completes the current deflate block and follows it with an empty stored block that is three bits plus filler bits to the next byte, followed by four bytes (00 00 ff ff).

If flush is set to Z_PARTIAL_FLUSH, all pending output is flushed to the output buffer, but the output is not aligned to a byte boundary. All of the input data so far will be available to the decompressor, as for Z_SYNC_FLUSH. This completes the current deflate block and follows it with an empty fixed codes block that is 10 bits long. This assures that enough bytes are output in order for the decompressor to finish the block before the empty fixed codes block.

If flush is set to Z_BLOCK, a deflate block is completed and emitted, as for Z_SYNC_FLUSH, but the output is not aligned on a byte boundary, and up to seven bits of the current block are held to be written as the next byte after the next deflate block is completed. In this case, the decompressor may not be provided enough bits at this point in order to complete decompression of the data provided so far to the compressor. It may need to wait for the next block to be emitted. This is for advanced applications that need to control the emission of deflate blocks.

If flush is set to Z_FULL_FLUSH, all output is flushed as with Z_SYNC_FLUSH, and the compression state is reset so that decompression can restart from this point if previous compressed data has been damaged or if random access is desired. Using Z_FULL_FLUSH too often can seriously degrade compression.

If deflate returns with avail_out == 0, this function must be called again with the same value of the flush parameter and more output space (updated avail_out), until the flush is complete (deflate returns with non-zero avail_out). In the case of a Z_FULL_FLUSH or Z_SYNC_FLUSH, make sure that avail_out is greater than six to avoid repeated flush markers due to avail_out == 0 on return.

If the parameter flush is set to Z_FINISH, pending input is processed, pending output is flushed and deflate returns with Z_STREAM_END if there was enough output space. If deflate returns with Z_OK or Z_BUF_ERROR, this function must be called again with Z_FINISH and more output space (updated avail_out) but no more input data, until it returns with Z_STREAM_END or an error. After deflate has returned Z_STREAM_END, the only possible operations on the stream are deflateReset or deflateEnd.

Z_FINISH can be used in the first deflate call after deflateInit if all the compression is to be done in a single step. In order to complete in one call, avail_out must be at least the value returned by deflateBound (see below). Then deflate is guaranteed to return Z_STREAM_END. If not enough output space is provided, deflate will not return Z_STREAM_END, and it must be called again as described above.

deflate() sets strm->adler to the Adler-32 checksum of all input read so far (that is, total_in bytes). If a gzip stream is being generated, then strm->adler will be the CRC-32 checksum of the input read so far. (See deflateInit2 below.)

deflate() may update strm->data_type if it can make a good guess about the input data type (Z_BINARY or Z_TEXT). If in doubt, the data is considered binary. This field is only for information purposes and does not affect the compression algorithm in any manner.

@return

int: Z_OK if some progress has been made (more input processed or more output produced), Z_STREAM_END if all input has been consumed and all output has been produced (only when flush is set to Z_FINISH), Z_STREAM_ERROR if the stream state was inconsistent (for example if next_in or next_out was Z_NULL or the state was inadvertently written over by the application), or Z_BUF_ERROR if no progress is possible (for example avail_in or avail_out was zero). Note that Z_BUF_ERROR is not fatal, and deflate() can be called again with more input and more output space to continue compressing.

@see third_party/zlib/zlib.h

deflateBound

deflateBound() returns an upper bound on the compressed size after deflation of sourceLen bytes. It must be called after deflateInit() or deflateInit2(), and after deflateSetHeader(), if used. This would be used to allocate an output buffer for deflation in a single pass, and so would be called before deflate(). If that first deflate() call is provided the sourceLen input bytes, an output buffer allocated to the size returned by deflateBound(), and the flush value Z_FINISH, then deflate() is guaranteed to return Z_STREAM_END. Note that it is possible for the compressed size to be larger than the value returned by deflateBound() if flush options other than Z_FINISH or Z_NO_FLUSH are used.

@return

unsigned long

@see third_party/zlib/zlib.h

deflateCopy

Sets destination stream as a complete copy of the source stream.

This function can be useful when several compression strategies will be tried, for example when there are several ways of pre-processing the input data with a filter. The streams that will be discarded should then be freed by calling deflateEnd. Note that deflateCopy duplicates the internal compression state which can be quite large, so this strategy is slow and can consume lots of memory.

@return

int: Z_OK if success, Z_MEM_ERROR if there was not enough memory, Z_STREAM_ERROR if the source stream state was inconsistent (such as zalloc being Z_NULL). msg is left unchanged in both source and destination.

@see third_party/zlib/zlib.h

deflateEnd

All dynamically allocated data structures for this stream are freed. This function discards any unprocessed input and does not flush any pending output.

@return

int: Z_OK if success, Z_STREAM_ERROR if the stream state was inconsistent, Z_DATA_ERROR if the stream was freed prematurely (some input or output was discarded). In the error case, msg may be set but then points to a static string (which must not be deallocated).

@see third_party/zlib/zlib.h

deflateGetDictionary

Returns the sliding dictionary being maintained by deflate. dictLength is set to the number of bytes in the dictionary, and that many bytes are copied to dictionary. dictionary must have enough space, where 32768 bytes is always enough. If deflateGetDictionary() is called with dictionary equal to Z_NULL, then only the dictionary length is returned, and nothing is copied. Similary, if dictLength is Z_NULL, then it is not set.

deflateGetDictionary() may return a length less than the window size, even when more than the window size in input has been provided. It may return up to 258 bytes less in that case, due to how zlib's implementation of deflate manages the sliding window and lookahead for matches, where matches can be up to 258 bytes long. If the application needs the last window-size bytes of input, then that would need to be saved by the application outside of zlib.

@return

int: Z_OK on success, or Z_STREAM_ERROR if the stream state is inconsistent.

@see third_party/zlib/zlib.h

deflateInit

Initializes the internal stream state for compression. The fields zalloc, zfree and opaque must be initialized before by the caller. If zalloc and zfree are set to Z_NULL, deflateInit updates them to use default allocation functions.

The compression level must be Z_DEFAULT_COMPRESSION, or between 0 and 9: 1 gives best speed, 9 gives best compression, 0 gives no compression at all (the input data is simply copied a block at a time). Z_DEFAULT_COMPRESSION requests a default compromise between speed and compression (currently equivalent to level 6).

@return

int: Z_OK if success, Z_MEM_ERROR if there was not enough memory, or Z_STREAM_ERROR if level is not a valid compression level. msg is set to null if there is no error message. deflateInit does not perform any compression: this will be done by deflate().

@see third_party/zlib/zlib.h

deflateInit2

This is another version of deflateInit with more compression options. The fields next_in, zalloc, zfree and opaque must be initialized before by the caller.

The method parameter is the compression method. It must be Z_DEFLATED in this version of the library.

The windowBits parameter is the base two logarithm of the window size (the size of the history buffer). It should be in the range 8..15 for this version of the library. Larger values of this parameter result in better compression at the expense of memory usage. The default value is 15 if deflateInit is used instead.

For the current implementation of deflate(), a windowBits value of 8 (a window size of 256 bytes) is not supported. As a result, a request for 8 will result in 9 (a 512-byte window). In that case, providing 8 to inflateInit2() will result in an error when the zlib header with 9 is checked against the initialization of inflate(). The remedy is to not use 8 with deflateInit2() with this initialization, or at least in that case use 9 with inflateInit2().

windowBits can also be -8..-15 for raw deflate. In this case, -windowBits determines the window size. deflate() will then generate raw deflate data with no zlib header or trailer, and will not compute a check value.

windowBits can also be greater than 15 for optional gzip encoding. Add 16 to windowBits to write a simple gzip header and trailer around the compressed data instead of a zlib wrapper. The gzip header will have no file name, no extra data, no comment, no modification time (set to zero), no header crc, and the operating system will be set to the appropriate value, if the operating system was determined at compile time. If a gzip stream is being written, strm->adler is a CRC-32 instead of an Adler-32.

For raw deflate or gzip encoding, a request for a 256-byte window is rejected as invalid, since only the zlib header provides a means of transmitting the window size to the decompressor.

The memLevel parameter specifies how much memory should be allocated for the internal compression state. memLevel=1 uses minimum memory but is slow and reduces compression ratio; memLevel=9 uses maximum memory for optimal speed. The default value is 8. See zconf.h for total memory usage as a function of windowBits and memLevel.

The strategy parameter is used to tune the compression algorithm. Use the value Z_DEFAULT_STRATEGY for normal data, Z_FILTERED for data produced by a filter (or predictor), Z_HUFFMAN_ONLY to force Huffman encoding only (no string match), or Z_RLE to limit match distances to one (run-length encoding). Filtered data consists mostly of small values with a somewhat random distribution. In this case, the compression algorithm is tuned to compress them better. The effect of Z_FILTERED is to force more Huffman coding and less string matching; it is somewhat intermediate between Z_DEFAULT_STRATEGY and Z_HUFFMAN_ONLY. Z_RLE is designed to be almost as fast as Z_HUFFMAN_ONLY, but give better compression for PNG image data. The strategy parameter only affects the compression ratio but not the correctness of the compressed output even if it is not set appropriately. Z_FIXED prevents the use of dynamic Huffman codes, allowing for a simpler decoder for special applications.

@return

int: Z_OK if success, Z_MEM_ERROR if there was not enough memory, or Z_STREAM_ERROR if any parameter is invalid (such as an invalid method). msg is set to null if there is no error message. deflateInit2 does not perform any compression: this will be done by deflate().

@see third_party/zlib/zlib.h

deflateParams

Dynamically update the compression level and compression strategy. The interpretation of level and strategy is as in deflateInit2(). This can be used to switch between compression and straight copy of the input data, or to switch to a different kind of input data requiring a different strategy. If the compression approach (which is a function of the level) or the strategy is changed, and if any input has been consumed in a previous deflate() call, then the input available so far is compressed with the old level and strategy using deflate(strm, Z_BLOCK). There are three approaches for the compression levels 0, 1..3, and 4..9 respectively. The new level and strategy will take effect at the next call of deflate().

If a deflate(strm, Z_BLOCK) is performed by deflateParams(), and it does not have enough output space to complete, then the parameter change will not take effect. In this case, deflateParams() can be called again with the same parameters and more output space to try again.

In order to assure a change in the parameters on the first try, the deflate stream should be flushed using deflate() with Z_BLOCK or other flush request until strm.avail_out is not zero, before calling deflateParams(). Then no more input data should be provided before the deflateParams() call. If this is done, the old level and strategy will be applied to the data compressed before deflateParams(), and the new level and strategy will be applied to the the data compressed after deflateParams().

deflateParams returns Z_OK on success, Z_STREAM_ERROR if the source stream state was inconsistent or if a parameter was invalid, or Z_BUF_ERROR if there was not enough output space to complete the compression of the available input data before a change in the strategy or approach. Note that in the case of a Z_BUF_ERROR, the parameters are not changed. A return value of Z_BUF_ERROR is not fatal, in which case deflateParams() can be retried with more output space.

@return

int

@see third_party/zlib/zlib.h

deflatePending

deflatePending() returns the number of bytes and bits of output that have been generated, but not yet provided in the available output. The bytes not provided would be due to the available output space having being consumed. The number of bits of output not provided are between 0 and 7, where they await more bits to join them in order to fill out a full byte. If pending or bits are Z_NULL, then those values are not set.

@return

int: Z_OK if success, or Z_STREAM_ERROR if the source stream state was inconsistent.

@see third_party/zlib/zlib.h

deflatePrime

deflatePrime() inserts bits in the deflate output stream. The intent is that this function is used to start off the deflate output with the bits leftover from a previous deflate stream when appending to it. As such, this function can only be used for raw deflate, and must be used before the first deflate() call after a deflateInit2() or deflateReset(). bits must be less than or equal to 16, and that many of the least significant bits of value will be inserted in the output.

@return

int: Z_OK if success, Z_BUF_ERROR if there was not enough room in the internal buffer to insert the bits, or Z_STREAM_ERROR if the source stream state was inconsistent.

@see third_party/zlib/zlib.h

deflateReset

This function is equivalent to deflateEnd followed by deflateInit, but does not free and reallocate the internal compression state. The stream will leave the compression level and any other attributes that may have been set unchanged.

deflateReset returns Z_OK if success, or Z_STREAM_ERROR if the source stream state was inconsistent (such as zalloc or state being Z_NULL).

@return

int

@see third_party/zlib/zlib.h

deflateSetDictionary

Initializes the compression dictionary from the given byte sequence without producing any compressed output. When using the zlib format, this function must be called immediately after deflateInit, deflateInit2 or deflateReset, and before any call of deflate. When doing raw deflate, this function must be called either before any call of deflate, or immediately after the completion of a deflate block, i.e. after all input has been consumed and all output has been delivered when using any of the flush options Z_BLOCK, Z_PARTIAL_FLUSH, Z_SYNC_FLUSH, or Z_FULL_FLUSH. The compressor and decompressor must use exactly the same dictionary (see inflateSetDictionary).

The dictionary should consist of strings (byte sequences) that are likely to be encountered later in the data to be compressed, with the most commonly used strings preferably put towards the end of the dictionary. Using a dictionary is most useful when the data to be compressed is short and can be predicted with good accuracy; the data can then be compressed better than with the default empty dictionary.

Depending on the size of the compression data structures selected by deflateInit or deflateInit2, a part of the dictionary may in effect be discarded, for example if the dictionary is larger than the window size provided in deflateInit or deflateInit2. Thus the strings most likely to be useful should be put at the end of the dictionary, not at the front. In addition, the current implementation of deflate will use at most the window size minus 262 bytes of the provided dictionary.

Upon return of this function, strm->adler is set to the Adler-32 value of the dictionary; the decompressor may later use this value to determine which dictionary has been used by the compressor. (The Adler-32 value applies to the whole dictionary even if only a subset of the dictionary is actually used by the compressor.) If a raw deflate was requested, then the Adler-32 value is not computed and strm->adler is not set.

@return

int: Z_OK if success, or Z_STREAM_ERROR if a parameter is invalid (e.g. dictionary being Z_NULL) or the stream state is inconsistent (for example if deflate has already been called for this stream or if not at a block boundary for raw deflate). deflateSetDictionary does not perform any compression: this will be done by deflate().

@see third_party/zlib/zlib.h

deflateSetHeader

Provides gzip header information for when a gzip stream is requested by deflateInit2(). deflateSetHeader() may be called after deflateInit2() or deflateReset() and before the first call of deflate(). The text, time, os, extra field, name, and comment information in the provided gz_header structure are written to the gzip header (xflag is ignored -- the extra flags are set according to the compression level). The caller must assure that, if not Z_NULL, name and comment are terminated with a zero byte, and that if extra is not Z_NULL, that extra_len bytes are available there. If hcrc is true, a gzip header crc is included. Note that the current versions of the command-line version of gzip (up through version 1.3.x) do not support header crc's, and will report that it is a "multi-part gzip file" and give up.

If deflateSetHeader is not used, the default gzip header has text false, the time set to zero, and os set to 255, with no extra, name, or comment fields. The gzip header is returned to the default state by deflateReset().

deflateSetHeader returns Z_OK if success, or Z_STREAM_ERROR if the source stream state was inconsistent.

@return

int

@see third_party/zlib/zlib.h

deflateTune

Fine tune deflate's internal compression parameters. This should only be used by someone who understands the algorithm used by zlib's deflate for searching for the best matching string, and even then only by the most fanatic optimizer trying to squeeze out the last compressed bit for their specific input data. Read the deflate.c source code for the meaning of the max_lazy, good_length, nice_length, and max_chain parameters.

deflateTune() can be called after deflateInit() or deflateInit2(), and returns Z_OK on success, or Z_STREAM_ERROR for an invalid deflate stream.

@return

int

@see third_party/zlib/zlib.h

DeleteFile

Deletes existing file.

@param

const unsigned short* lpPathName

@return

int

@note this wrapper takes care of ABI, STRACE(), and __winerr()

@see libc/intrin/deletefile.c

DeserializeDnsHeader

Serializes DNS message h to wire.

@param

struct DnsHeader* h
const unsigned char* p

@return

void: number of bytes read (always 12) or -1 w/ errno

@see libc/dns/dnsheader.c

DestroyHttpMessage

Destroys HTTP message parser.

@param

struct HttpMessage* r

@return

void

@see net/http/parsehttpmessage.c

DeviceIoControl

Does device file stuff on the New Technology.

@param

long hDevice
unsigned int dwIoControlCode
void* lpInBuffer
unsigned int nInBufferSize
void* lpOutBuffer
unsigned int nOutBufferSize
unsigned int* lpBytesReturned
struct inout_lpOverlapped* lpOverlapped

@return

int: handle, or -1 on failure

@note this wrapper takes care of ABI, STRACE(), and __winerr()

@see libc/intrin/deviceiocontrol.c

__die

Aborts process after printing a backtrace.

If a debugger is present then this will trigger a breakpoint.

@noreturn

@see libc/log/die.c

difftime

@param

long time1
long time0

@return

double

@see libc/time/difftime.c

dirfd

Returns file descriptor associated with DIR object.

@param

struct dirstream* dir

@return

int

@threadsafe

@see libc/stdio/dirstream.c

dirname

Returns directory portion of path, e.g.

path     │ dirname() │ basename()
─────────────────────────────────
.        │ .         │ .
..       │ .         │ ..
/        │ /         │ /
usr      │ .         │ usr
/usr/    │ /         │ usr
/usr/lib │ /usr      │ lib

@param

char* path: is UTF-8 and may be mutated, but not expanded in length

@return

char*: pointer to path, or inside path, or to a special r/o string

@see basename()

@see SUSv2

@see libc/fmt/dirname.c

div

@param

int num
int den

@return

struct div_t

@see libc/fmt/div.c

__divmodti4

Divides 128-bit signed integers w/ remainder.

@param

__int128 a: is numerator
__int128 b: is denominator
unsigned __int128* opt_out_rem: receives euclidean division remainder if not null

@return

__int128: quotient or result of division

@note rounds towards zero

@see third_party/compiler_rt/divmodti4.c

__divti3

Divides 128-bit signed integers.

@param

__int128 a: is numerator
__int128 b: is denominator

@return

__int128: quotient or result of division

@note rounds towards zero

@see third_party/compiler_rt/divti3.c

djbsort

D.J. Bernstein's outrageously fast integer sorting algorithm.

@param

int* a
unsigned long n

@return

void

@see libc/str/djbsort.c

djbsort_avx2

D.J. Bernstein's outrageously fast integer sorting algorithm.

@param

rdi: is int32 array
rsi: is number of elements in rdi

@return

@note public domain

@see en.wikipedia.org/wiki/Sorting_network

@see libc/nexgen32e/djbsort-avx2.S

dl_iterate_phdr

@param

int(*)() callback
void* data

@return

int

@see libc/runtime/ldso.c

dlbulk_free

@param

void** array
unsigned long nelem

@return

unsigned long

@see third_party/dlmalloc/dlmalloc.c

dlcalloc

@param

unsigned long n_elements
unsigned long elem_size

@return

void*

@see third_party/dlmalloc/dlmalloc.c

dlclose

@param

void* handle

@return

int

@see libc/runtime/ldso.c

dlerror

@return

char*

@see libc/runtime/ldso.c

dlfree

@param

void* mem

@return

void

@see third_party/dlmalloc/dlmalloc.c

dlindependent_calloc

@param

unsigned long n_elements
unsigned long elem_size
void** chunks

@return

void**

@see third_party/dlmalloc/dlmalloc.c

dlindependent_comalloc

@param

unsigned long n_elements
unsigned long* sizes
void** chunks

@return

void**

@see third_party/dlmalloc/dlmalloc.c

dlmallinfo

@param

struct nm*

@return

struct nm

@see third_party/dlmalloc/dlmalloc.c

dlmalloc

@param

unsigned long bytes

@return

void*

@see third_party/dlmalloc/dlmalloc.c

dlmalloc_abort

@return

void

@see third_party/dlmalloc/dlmalloc_abort.greg.c

dlmalloc_footprint

@return

unsigned long

@see third_party/dlmalloc/dlmalloc.c

dlmalloc_footprint_limit

@return

unsigned long

@see third_party/dlmalloc/dlmalloc.c

dlmalloc_inspect_all

@param

void(*)() handler
void* arg

@return

void

@see third_party/dlmalloc/dlmalloc.c

dlmalloc_max_footprint

@return

unsigned long

@see third_party/dlmalloc/dlmalloc.c

dlmalloc_requires_more_vespene_gas

Acquires more system memory for dlmalloc.

@param

unsigned long size

@return

void*: memory map address on success, or null w/ errno

@see third_party/dlmalloc/vespene.c

dlmalloc_set_footprint_limit

@param

unsigned long bytes

@return

unsigned long

@see third_party/dlmalloc/dlmalloc.c

dlmalloc_trim

@param

unsigned long pad

@return

int

@see third_party/dlmalloc/dlmalloc.c

dlmalloc_usable_size

@param

void* mem

@return

unsigned long

@see third_party/dlmalloc/dlmalloc.c

dlmallopt

@param

int param_number
int value

@return

int

@see third_party/dlmalloc/dlmalloc.c

dlmemalign

@param

unsigned long alignment
unsigned long bytes

@return

void*

@see third_party/dlmalloc/dlmalloc.c

dlopen

@param

const char* file
int mode

@return

void*

@see libc/runtime/ldso.c

dlposix_memalign

@param

void** pp
unsigned long alignment
unsigned long bytes

@return

int

@see third_party/dlmalloc/dlmalloc.c

dlpvalloc

@param

unsigned long bytes

@return

void*

@see third_party/dlmalloc/dlmalloc.c

dlrealloc

@param

void* oldmem
unsigned long bytes

@return

void*

@see third_party/dlmalloc/dlmalloc.c

dlrealloc_in_place

@param

void* oldmem
unsigned long bytes

@return

void*

@see third_party/dlmalloc/dlmalloc.c

dlsym

@param

void* handle
const char* name

@return

void*

@see libc/runtime/ldso.c

dlvalloc

@param

unsigned long bytes

@return

void*

@see third_party/dlmalloc/dlmalloc.c

__dos2errno

Translates Windows error using superset of consts.sh.

This function is called by __winerr(). It can only be used on Windows, because it returns an errno. Normally, errnos will be programmed to be the same as DOS errnos, per consts.sh. But since there's so many more errors in DOS, this function provides an added optional benefit mapping additional constants onto the errnos in consts.sh.

@param

unsigned int error

@return

int

@see libc/intrin/dos2errno.c

DosDateTimeToUnix

Converts MS-DOS timestamp to UNIX.

@param

unsigned int date
unsigned int time

@return

long

@note type signature supports dates greater than 2100

@see PKZIP, FAT

@see libc/str/dosdatetimetounix.c

dprintf

Formats string directly to file descriptor.

@param

int fd
const char* fmt
...

@return

int

@see libc/calls/dprintf.c

drand48

@return

double

@see third_party/musl/rand48.c

drem

remainder(𝑥,𝑦) means (𝑥 rem 𝑦) w/ rint()-style rounding.

@param

𝑥: is double passed in lower half of %xmm0
𝑦: is double passed in lower half of %xmm1

@return

: remainder ∈ (-|𝑦|,|𝑦|) in %xmm0

@define 𝑥-rint(𝑥/𝑦)*𝑦

@see fmod(), emod(), operator%

@see libc/tinymath/remainder.S

dsleep

Sleeps w/ higher precision.

@param

long double secs

@return

long double

@see libc/time/dsleep.c

dtime

Returns seconds since epoch w/ high-precision.

@param

int clockid: can be CLOCK_{REALTIME,MONOTONIC}, etc.

@return

long double

@see libc/calls/dtime.c

dtoa

@param

double d0
int mode
int ndigits
int* decpt
int* sign
char** rve

@return

char*

@see third_party/gdtoa/dtoa.c

DumpHexc

Turns data into "\x00..." string literal.

@param

const char* p
unsigned long n
unsigned long* z

@return

char*

@see libc/stdio/dumphexc.c

dup

Duplicates file descriptor.

The O_CLOEXEC flag shall be cleared from the resulting file descriptor; see dup3() to preserve it.

@param

int fd: remains open afterwards

@return

int: some arbitrary new number for fd

@raise EPERM if pledge() is in play without stdio

@raise ENOTSUP if fd is a zip file descriptor

@raise EBADF if fd is negative or not open

@asyncsignalsafe

@vforksafe

@see libc/calls/dup.c

dup2

Duplicates file descriptor, granting it specific number.

The O_CLOEXEC flag shall be cleared from the resulting file descriptor; see dup3() to preserve it.

Unlike dup3(), the dup2() function permits oldfd and newfd to be the same, in which case the only thing this function does is test if oldfd is open.

@param

int oldfd: isn't closed afterwards
int newfd: if already assigned, is silently closed beforehand; unless it's equal to oldfd, in which case dup2() is a no-op

@return

int: new file descriptor, or -1 w/ errno

@raise EPERM if pledge() is in play without stdio

@raise EMFILE if RLIMIT_NOFILE has been reached

@raise ENOTSUP if oldfd is on zip file system

@raise EINTR if a signal handler was called

@raise EBADF is newfd negative or too big

@raise EBADF is oldfd isn't open

@asyncsignalsafe

@vforksafe

@see libc/calls/dup2.c

dup3

Duplicates file descriptor/handle.

On Windows, we can't guarantee the desired file descriptor is used. We can however remap the standard handles (non-atomically) if their symbolic names are used.

@param

int oldfd: isn't closed afterwards
int newfd: if already assigned, is silently closed beforehand; unless it's equal to oldfd, in which case dup2() is a no-op
int flags: may have O_CLOEXEC which is needed to preserve the close-on-execve() state after file descriptor duplication

@return

int: newfd on success, or -1 w/ errno

@raise ENOTSUP if oldfd is a zip file descriptor

@raise EPERM if pledge() is in play without stdio

@raise EINVAL if flags has unsupported bits

@raise EINTR if a signal handler was called

@raise EBADF is newfd negative or too big

@raise EINVAL if newfd equals oldfd

@raise EBADF is oldfd isn't open

@see dup(), dup2()

@see libc/calls/dup3.c

E2BIG

Argument list too errno_t.

@type

const int

@see libc/errno.h

EACCES

Permission denied.

@type

const int

@see libc/errno.h

eaccess

Performs access() check using effective user/group id.

@param

const char* filename
int amode

@return

int

@see libc/calls/eaccess.c

EADDRINUSE

Address already in use.

@type

const int

@see libc/errno.h

EADDRNOTAVAIL

Address not available.

@type

const int

@see libc/errno.h

EAFNOSUPPORT

Address family not supported.

@type

const int

@see libc/errno.h

EAGAIN

Resource temporarily unavailable (e.g. SO_RCVTIMEO expired, too many processes, too much memory locked, read or write with O_NONBLOCK needs polling, etc.).

@type

const int

@see libc/errno.h

EALREADY

Connection already in progress.

@type

const int

@see libc/errno.h

EBADF

Bad file descriptor.

@type

const int

@see libc/errno.h

EBADMSG

Bad message.

@type

const int

@see libc/errno.h

EBUSY

Device or resource busy.

@type

const int

@see libc/errno.h

ECANCELED

Operation canceled.

@type

const int

@see libc/errno.h

ECHILD

No child process.

@type

const int

@see libc/errno.h

ECONNABORTED

Connection reset before accept.

@type

const int

@see libc/errno.h

ECONNREFUSED

Connection refused error.

@type

const int

@see libc/errno.h

ECONNRESET

Connection reset by client.

@type

const int

@see libc/errno.h

ecvt

@param

double value
int ndigit
int* decpt
int* sign

@return

char*

@see libc/stdio/ecvt.c

EDEADLK

Resource deadlock avoided.

@type

const int

@see libc/errno.h

EDESTADDRREQ

Destination address required.

@type

const int

@see libc/errno.h

EDOM

Mathematics argument out of domain of function.

@type

const int

@see libc/errno.h

EDQUOT

Disk quota exceeded.

@type

const int

@see libc/errno.h

EEXIST

File exists.

@type

const int

@see libc/errno.h

EFAULT

Pointer passed to system call that would otherwise segfault.

@type

const int

@see libc/errno.h

EFBIG

File too large.

@type

const int

@see libc/errno.h

EfiMain

EFI Application Entrypoint.

This entrypoint is mutually exclusive from WinMain since Windows apps and EFI apps use the same PE binary format. So if you want to trade away Windows so that you can use UEFI instead of the normal BIOS boot process, do this:

STATIC_YOINK("EfiMain");
int main() { ... }

You can use QEMU to test this, but please note that UEFI goes thousands of times slower than the normal BIOS boot

qemu-system-x86_64 \
  -bios OVMF.fd    \
  -nographic       \
  -net none        \
  -drive format=raw,file=fat:rw:o/tool/viz
FS0:
deathstar.com

@param

unsigned long ImageHandle
struct EFI_SYSTEM_TABLE* SystemTable

@return

unsigned long

@see libc/dce.h

@see libc/runtime/efimain.greg.c

_EfiPostboot

Start the Cosmopolitan runtime after exiting UEFI Boot Services.

@param

rdi: is mm
rsi: is new pml4t
rdx: is argc
rcx: is argv

@return

@see libc/runtime/efimain.greg.c

@see libc/runtime/efipostboot.S

EFTYPE

Inappropriate file type or format. (BSD only)

@type

const int

@see libc/errno.h

EHOSTDOWN

Host down error.

@type

const int

@see libc/errno.h

EHOSTUNREACH

Host unreachable error.

@type

const int

@see libc/errno.h

EIDRM

Identifier removed.

@type

const int

@see libc/errno.h

EILSEQ

Unicode decoding error.

@type

const int

@see libc/errno.h

EINPROGRESS

Operation already in progress.

@type

const int

@see libc/errno.h

EINTR

The greatest of all errnos.

@type

const int

@see libc/errno.h

EINVAL

Invalid argument.

@type

const int

@see libc/errno.h

EIO

Unix consensus.

@type

const int

@see libc/errno.h

EISCONN

Socket is connected.

@type

const int

@see libc/errno.h

EISDIR

Is a a directory.

@type

const int

@see libc/errno.h

ElevateSeDebugPrivilege

@return

int

@see libc/calls/sedebug.c

ELOOP

Too many levels of symbolic links.

@type

const int

@see libc/errno.h

EMEDIUMTYPE

Wrong medium type.

@type

const int

@see libc/errno.h

EMFILE

Too many open files.

@type

const int

@see libc/errno.h

EMLINK

Too many links.

@type

const int

@see libc/errno.h

EMSGSIZE

Message too errno_t.

@type

const int

@see libc/errno.h

EMULTIHOP

Multihop attempted.

@type

const int

@see libc/errno.h

__enable_tls

Enables thread local storage for main process.

                         %fs Linux/BSDs
                          │
       _Thread_local      │ __get_tls()
┌───┬──────────┬──────────┼───┐
│pad│  .tdata  │  .tbss   │tib│
└───┴──────────┴──────────┼───┘
                          │
             Windows/Mac %gs

This function is always called by the core runtime to guarantee TLS is always available to your program. You must build your code using -mno-tls-direct-seg-refs if you want to use _Thread_local.

You can use __get_tls() to get the linear address of your tib. When accessing TLS via privileged code you must use __get_tls_privileged because we need code morphing to support The New Technology and XNU

On XNU and The New Technology, this function imposes 1ms of latency during startup for larger binaries like Python.

If you don't want TLS and you're sure you're not using it, then you can disable it as follows:

int main() {
  __tls_enabled = false;
  // do stuff
}

This is useful if you want to wrestle back control of %fs using the arch_prctl() function. However, such programs might not be portable and your errno variable also won't be thread safe anymore.

@return

void

@see libc/runtime/enable_tls.c

ENAMETOOLONG

Filename too errno_t.

@type

const int

@see libc/errno.h

EncodeBase64

Encodes binary to base64 ascii representation.

@param

const char* data: is input value
unsigned long size: if -1 implies strlen
unsigned long* out_size: if non-NULL receives output length

@return

char*: allocated NUL-terminated buffer, or NULL w/ errno

@see net/http/encodebase64.c

EncodeHttpHeaderValue

Encodes HTTP header value.

This operation involves the following:

Trim whitespace.
Turn UTF-8 into ISO-8859-1.
Make sure no C0 or C1 control codes are present (except tab).

If the input value isn't thompson-pike encoded then this implementation will fall back to latin1 in most cases.

@param

const char* data: is input value
unsigned long size: if -1 implies strlen
unsigned long* out_size: if non-NULL receives output length on success

@return

char*: allocated NUL-terminated string, or NULL w/ errno

@see net/http/encodehttpheadervalue.c

EncodeLatin1

Encodes UTF-8 to ISO-8859-1.

@param

const char* p: is input value
unsigned long n: if -1 implies strlen
unsigned long* z: if non-NULL receives output length
int f: can kControlC0, kControlC1, kControlWs to forbid

@return

char*: allocated NUL-terminated buffer, or NULL w/ errno

@error EILSEQ means UTF-8 found we can't or won't re-encode

@error ENOMEM means malloc() failed

@see net/http/encodelatin1.c

EncodeNf32

Encodes u32 as ANSI Nf sequence content.

@param

char* p
unsigned int x

@return

char*

@see libc/fmt/encodenf32.c

EncodeUrl

Encodes URL.

@param

struct Url* h
unsigned long* z: if not null receives string length of result

@return

char*: nul-terminated url string needing free

@see ParseUrl()

@see net/http/encodeurl.c

encrypt

@param

char* block
int edflag

@return

void

@see third_party/musl/encrypt.c

endgrent

@return

void

@see third_party/musl/grp.c

endhostent

@return

void

@see libc/dns/hostent.c

endmntent

@param

struct FILE* f

@return

int

@see third_party/musl/mntent.c

endnetent

@return

void

@see libc/dns/netent.c

endprotoent

@return

void

@see libc/dns/protoent.c

endpwent

@return

void

@see third_party/musl/pwd.c

endservent

@return

void

@see libc/dns/servent.c

_endswith

Returns true if s has suffix.

@param

const char* s: is a NUL-terminated string
const char* suffix: is also NUL-terminated

@return

_Bool

@see libc/str/endswith.c

_endswith16

Returns true if s has suffix.

@param

const unsigned short* s: is a NUL-terminated string
const unsigned short* suffix: is also NUL-terminated

@return

_Bool

@see libc/str/endswith16.c

endutxent

Closes user accounting database.

@return

@note unsupported

@see libc/runtime/endutxent.S

ENETDOWN

Network is down.

@type

const int

@see libc/errno.h

ENETRESET

Connection reset by network.

@type

const int

@see libc/errno.h

ENETUNREACH

Host is unreachable.

@type

const int

@see libc/errno.h

ENFILE

Too many open files in system.

@type

const int

@see libc/errno.h

ENOBUFS

No buffer space available.

@type

const int

@see libc/errno.h

ENODATA

No data.

@type

const int

@see libc/errno.h

ENODEV

No such device.

@type

const int

@see libc/errno.h

ENOENT

No such file or directory.

@type

const int

@see libc/errno.h

ENOEXEC

Exec format error.

@type

const int

@see libc/errno.h

ENOLCK

No locks available.

@type

const int

@see libc/errno.h

ENOLINK

Link severed.

@type

const int

@see libc/errno.h

ENOMEDIUM

No medium found.

@type

const int

@see libc/errno.h

ENOMEM

We require more vespene gas.

@type

const int

@see libc/errno.h

ENOMSG

No message error.

@type

const int

@see libc/errno.h

ENONET

No network.

@type

const int

@see libc/errno.h

ENOPROTOOPT

Protocol not available.

@type

const int

@see libc/errno.h

ENOSPC

No space left on device.

@type

const int

@see libc/errno.h

ENOSR

Out of streams resources.

@type

const int

@see libc/errno.h

ENOSTR

No string.

@type

const int

@see libc/errno.h

ENOSYS

System call unavailable.

@type

const int

@note kNtErrorInvalidFunction on NT

@see libc/errno.h

ENOTBLK

Block device required.

@type

const int

@see libc/errno.h

ENOTCONN

Socket is not connected.

@type

const int

@see libc/errno.h

ENOTDIR

Not a directory.

@type

const int

@see libc/errno.h

ENOTEMPTY

Directory not empty.

@type

const int

@see libc/errno.h

ENOTRECOVERABLE

State not recoverable.

@type

const int

@see libc/errno.h

ENOTSOCK

Not a socket.

@type

const int

@see libc/errno.h

ENOTSUP

Operation not supported.

@type

const int

@see libc/errno.h

ENOTTY

Inappropriate i/o control operation.

@type

const int

@see libc/errno.h

__ensurefds

Grows file descriptor array memory if needed.

@param

int fd

@return

int

@asyncsignalsafe

@threadsafe

@see libc/calls/reservefd.c

__ensurefds_unlocked

Grows file descriptor array memory if needed.

@param

int fd

@return

int

@see libc/runtime/memtrack64.txt

@see libc/runtime/memtrack32.txt

@asyncsignalsafe

@see libc/calls/reservefd.c

ENXIO

No such device or address.

@type

const int

@see libc/errno.h

EOPNOTSUPP

Socket operation not supported.

@type

const int

@see libc/errno.h

EOVERFLOW

Overflow error.

@type

const int

@see libc/errno.h

EOWNERDEAD

Owner died.

@type

const int

@see libc/errno.h

EPERM

Operation not permitted.

@type

const int

@note kNtErrorInvalidAccess on NT

@see libc/errno.h

EPFNOSUPPORT

Protocol family not supported.

@type

const int

@see libc/errno.h

EPIPE

Broken pipe.

@type

const int

@see libc/errno.h

epoll_create

Creates new epoll instance.

@param

int size: is ignored but must be greater than zero

@return

int: epoll file descriptor, or -1 on failure

@see libc/sock/epoll.c

epoll_create1

Creates new epoll instance.

@param

int flags: must be zero or can have O_CLOEXEC

@return

int: epoll file descriptor, or -1 on failure

@see libc/sock/epoll.c

epoll_ctl

Controls which socket events are monitored.

It is recommended to always explicitly remove a socket from its epoll set using EPOLL_CTL_DEL before closing it. As on Linux, your closed sockets are automatically removed from the epoll set, but wepoll may not be able to detect that a socket was closed until the next call to epoll_wait().

@param

int epfd: is file descriptor created by epoll_create()
int op: can be EPOLL_CTL_{ADD,MOD,DEL}
int fd: is file descriptor to monitor
struct epoll_event* ev: is ignored if op is EPOLL_CTL_DEL

@return

int: 0 on success, or -1 w/ errno

@error ENOTSOCK on Windows if fd isn't a socket :(

@see libc/sock/epoll.c

epoll_wait

Receives socket events.

@param

int epfd
struct epoll_event* events: will receive information about what happened
int maxevents: is array length of events
int timeoutms: is milliseconds, 0 to not block, or -1 for forever

@return

int: number of events stored, 0 on timeout, or -1 w/ errno

@cancellationpoint

@norestart

@see libc/sock/epoll.c

EPROTO

Protocol error.

@type

const int

@see libc/errno.h

EPROTONOSUPPORT

Protocol not supported.

@type

const int

@see libc/errno.h

EPROTOTYPE

Protocol wrong type for socket.

@type

const int

@see libc/errno.h

erand48

@param

unsigned short* s

@return

double

@see third_party/musl/rand48.c

ERANGE

Result too large.

@type

const int

@see libc/errno.h

EREMOTE

Remote error.

@type

const int

@see libc/errno.h

ERESTART

Please restart syscall.

@type

const int

@see libc/errno.h

erf

Returns error function of 𝑥.

@param

double x

@return

double

@see libc/tinymath/erf.c

erfc

Returns complementary error function of 𝑥.

@param

double x

@return

double

@see libc/tinymath/erf.c

erfcf

@param

float x

@return

float

@see libc/tinymath/erff.c

erff

@param

float x

@return

float

@see libc/tinymath/erff.c

EROFS

Read-only filesystem.

@type

const int

@see libc/errno.h

err

@param

int eval
const char* fmt
...

@return

void

@see libc/log/err.c

err_set_exit

@param

void(*)() ef

@return

void

@see libc/log/err.c

err_set_file

@param

void* fp

@return

void

@see libc/log/err.c

errc

@param

int eval
int code
const char* fmt
...

@return

void

@see libc/log/err.c

__errno

Global variable for last error.

The system call wrappers update this with WIN32 error codes. Unlike traditional libraries, Cosmopolitan error codes are defined as variables. By convention, system calls and other functions do not update this variable when nothing's broken.

@type

int

@see libc/sysv/consts.sh

@see libc/sysv/errfuns.h

@see __errno_location() stable abi

@see libc/sysv/errno.c

__errno_location

Returns address of errno variable.

@return

int*

@see libc/sysv/errno_location.greg.c

errx

@param

int eval
const char* fmt
...

@return

void

@see libc/log/err.c

_escapedos

Escapes command so DOS can run it.

@param

unsigned short* buffer
unsigned int buflen
const unsigned short* unquoted
unsigned int len

@return

_Bool

@see Iain Patterson's NSSM for original code in public domain

@see libc/str/escapedos.c

EscapeFragment

Escapes URL fragment.

@param

const char* p: is input value
unsigned long n: if -1 implies strlen
unsigned long* z: if non-NULL receives output length

@return

char*: allocated NUL-terminated buffer, or NULL w/ errno

@see net/http/escapefragment.c

EscapeHost

Escapes URL host or registry name.

@param

const char* p: is input value
unsigned long n: if -1 implies strlen
unsigned long* z: if non-NULL receives output length

@return

char*: allocated NUL-terminated buffer, or NULL w/ errno

@see net/http/escapehost.c

EscapeHtml

Escapes HTML entities.

@param

const char* p: is input value
unsigned long n: if -1 implies strlen
unsigned long* z: if non-NULL receives output length

@return

char*: allocated NUL-terminated buffer, or NULL w/ errno

@see net/http/escapehtml.c

EscapeIp

Escapes URL IP-literal.

This is the same as EscapeHost except colon is permitted.

@param

const char* p: is input value
unsigned long n: if -1 implies strlen
unsigned long* z: if non-NULL receives output length

@return

char*: allocated NUL-terminated buffer, or NULL w/ errno

@see net/http/escapeip.c

EscapeJsStringLiteral

Escapes UTF-8 data for JavaScript or JSON string literal.

HTML entities and forward slash are escaped too for added safety. Single quote (') is \uxxxx-encoded for consistency, as it's allowed in JavaScript, but not in JSON strings.

We assume the UTF-8 is well-formed and can be represented as UTF-16. Things that can't be decoded will fall back to binary. Things that can't be encoded will use invalid codepoint markers. This function is agnostic to numbers that have been used with malicious intent in the past under buggy software. Noncanonical encodings such as overlong NUL are canonicalized as NUL. Therefore it isn't necessary to say EscapeJsStringLiteral(Underlong(𝑥)) since EscapeJsStringLiteral(𝑥) will do the same thing.

@param

char** r: is realloc'able output buffer reused between calls
unsigned long* y: is used to track byte length of *r
const char* p: is input value
unsigned long n: if -1 implies strlen
unsigned long* z

@return

char*: *r on success, or null w/ errno

@see net/http/escapejsstringliteral.c

EscapeParam

Escapes query/form name/parameter.

@param

const char* p: is input value
unsigned long n: if -1 implies strlen
unsigned long* z: if non-NULL receives output length

@return

char*: allocated NUL-terminated buffer, or NULL w/ errno

@see net/http/escapeparam.c

EscapePass

Escapes URL password.

@param

const char* p: is input value
unsigned long n: if -1 implies strlen
unsigned long* z: if non-NULL receives output length

@return

char*: allocated NUL-terminated buffer, or NULL w/ errno

@see net/http/escapepass.c

EscapePath

Escapes URL path.

This is the same as EscapePathSegment() except slash is allowed.

@param

const char* p: is input value
unsigned long n: if -1 implies strlen
unsigned long* z: if non-NULL receives output length

@return

char*: allocated NUL-terminated buffer, or NULL w/ errno

@see net/http/escapepath.c

EscapeSegment

Escapes URL path segment.

Please note this will URI encode the slash character. That's because segments are the labels between the slashes in a path.

@param

const char* p: is input value
unsigned long n: if -1 implies strlen
unsigned long* z: if non-NULL receives output length

@return

char*: allocated NUL-terminated buffer, or NULL w/ errno

@see net/http/escapesegment.c

EscapeUrl

Escapes URL component using generic table.

This function is agnostic to the underlying charset. Always using UTF-8 is a good idea.

@param

const char* p: is input value
unsigned long n: if -1 implies strlen
unsigned long* z: if non-NULL receives output length
const char* T

@return

char*: allocated NUL-terminated buffer, or NULL w/ errno

@see kEscapeAuthority

@see kEscapeIpLiteral

@see kEscapePath

@see kEscapePathSegment

@see kEscapeParam

@see kEscapeFragment

@see net/http/escapeurl.c

EscapeUrlView

Escapes URL component using generic table w/ stpcpy() api.

@param

char* p
struct fragment* v
const char* T

@return

char*

@see net/http/escapeurlview.c

EscapeUser

Escapes URL user name.

@param

const char* p: is input value
unsigned long n: if -1 implies strlen
unsigned long* z: if non-NULL receives output length

@return

char*: allocated NUL-terminated buffer, or NULL w/ errno

@see net/http/escapeuser.c

ESHUTDOWN

Cannot send after transport endpoint shutdown.

@type

const int

@see libc/errno.h

ESOCKTNOSUPPORT

Socket type not supported.

@type

const int

@see libc/errno.h

ESPIPE

Invalid seek.

@type

const int

@see libc/errno.h

ESRCH

No such process.

@type

const int

@see libc/errno.h

ESTALE

Stale error.

@type

const int

@see libc/errno.h

ETIME

Timer expired.

@type

const int

@see libc/errno.h

ETIMEDOUT

Connection timed out.

@type

const int

@see libc/errno.h

ETOOMANYREFS

Too many references: cannot splice.

@type

const int

@see libc/errno.h

ETXTBSY

Won't open executable that's executing in write mode.

@type

const int

@see libc/errno.h

euidaccess

Performs access() check using effective user/group id.

@param

const char* filename
int amode

@return

int

@see libc/calls/euidaccess.c

EUSERS

Too many users.

@type

const int

@see libc/errno.h

EXDEV

Improper link.

@type

const int

@see libc/errno.h

execl

Executes program, with current environment.

The current process is replaced with the executed one.

@param

const char* exe
const char* arg
...

@return

int: doesn't return on success, otherwise -1 w/ errno

@asyncsignalsafe

@vforksafe

@see libc/calls/execl.c

execle

Executes program, with custom environment.

The current process is replaced with the executed one.

@param

const char* exe
const char* arg
...

@return

int: doesn't return on success, otherwise -1 w/ errno

@asyncsignalsafe

@vforksafe

@see libc/calls/execle.c

execlp

Executes program, with PATH search and current environment.

The current process is replaced with the executed one.

@param

const char* prog: is program to launch (may be PATH searched)
const char* arg
...

@return

int: doesn't return on success, otherwise -1 w/ errno

@asyncsignalsafe

@vforksafe

@see libc/calls/execlp.c

execv

Replaces process with specific program, using default environment.

@param

const char* exe
char** argv

@return

int

@asyncsignalsafe

@vforksafe

@see libc/calls/execv.c

execve

Replaces current process with program.

On Windows, argv and envp can't contain binary strings. They need to be valid UTF-8 in order to round-trip the WIN32 API, without being corrupted.

@param

const char* prog
char** argv
char** envp

@return

int: doesn't return, or -1 w/ errno

@asyncsignalsafe

@vforksafe

@see libc/calls/execve.c

execvp

Replaces process, with path search, using default environment.

@param

const char* file
char** argv

@return

int

@asyncsignalsafe

@vforksafe

@see libc/calls/execvp.c

execvpe

Executes program, with path environment search.

The current process is replaced with the executed one.

@param

const char* prog: is the program to launch
char** argv: is [file,argv₁..argvₙ₋₁,NULL]
char** envp: is ["key=val",...,NULL]

@return

int: doesn't return on success, otherwise -1 w/ errno

@asyncsignalsafe

@vforksafe

@see libc/calls/execvpe.c

exit

Exits process with grace.

This calls functions registered by atexit() before terminating the current process, and any associated threads. It also calls all the legacy linker registered destructors in reversed order

This implementation allows exit() to be called recursively via atexit() handlers.

@param

int exitcode: is masked with 255

@noreturn

@see _Exit()

@see libc/runtime/exit.c

_exit

Terminates process, ignoring destructors and atexit() handlers.

When running on bare metal, this function will reboot your computer by hosing the interrupt descriptors and triple faulting the system.

@param

int exitcode: is masked with 255

@noreturn

@asyncsignalsafe

@vforksafe

@see libc/runtime/exit2.c

_Exit

Terminates process, ignoring destructors and atexit() handlers.

When running on bare metal, this function will reboot your computer by hosing the interrupt descriptors and triple faulting the system.

@param

int exitcode: is masked with 255 on unix (but not windows)

@noreturn

@asyncsignalsafe

@threadsafe

@vforksafe

@see libc/intrin/exit.c

_Exit1

Terminates thread with raw system call.

The function you want is pthread_exit(). If you call this function whilst using the pthreads then your joiners might not get woken up on non-Linux platforms where we zero __get_tls()->tib_tid manually

If this is the main thread, or an orphaned child thread, then this function is equivalent to exiting the process; however, rc shall only be reported to the parent process on Linux, FreeBSD & Windows whereas on other platforms, it'll be silently coerced to zero.

@param

int rc: only works on Linux and Windows

@noreturn

@see cthread_exit()

@threadsafe

@see libc/intrin/exit1.greg.c

exp

Returns 𝑒^x.

@param

𝑥: is float scalar in low quarter of %xmm0

@return

: float scalar in low quarter of %xmm0

@see libc/tinymath/exp-tiny.S

exp10

Returns 10^x.

@param

𝑥: is double scalar in low half of %xmm0

@return

: double scalar in low half of %xmm0

@see pow(), exp()

@see libc/tinymath/exp10.S

exp10f

Returns 10^x.

@param

𝑥: is float scalar in low quarter of %xmm0

@return

: float scalar in low quarter of %xmm0

@see libc/tinymath/exp10f.S

exp10l

Returns 10^x.

@param

𝑥: is an 80-bit long double passed on stack in 16-bytes

@return

: result of exponentiation on FPU stack in %st

@see libc/tinymath/exp10l.S

exp2

Returns 2^𝑥.

@param

𝑥: is a double passed in the lower quadword of %xmm0

@return

: result in lower quadword of %xmm0

@see libc/tinymath/exp2-tiny.S

exp2f

Returns 2^𝑥.

@param

𝑥: is a float passed in the lower quarter of %xmm0

@return

: result in lower quarter of %xmm0

@see libc/tinymath/exp2f-tiny.S

exp2l

Returns 2^𝑥.

@param

𝑥: is an 80-bit long double passed on stack in 16-bytes

@return

: result of exponentiation on FPU stack in %st

@see libc/tinymath/exp2l.S

expf

Returns 𝑒^x.

@param

𝑥: is double scalar in low half of %xmm0

@return

: double scalar in low half of %xmm0

@see libc/tinymath/expf-tiny.S

expl

Returns 𝑒^x.

@param

𝑥: is an 80-bit long double passed on stack in 16-bytes

@return

: result of exponentiation on FPU stack in %st

@see libc/tinymath/expl.S

explicit_bzero

Sets memory to zero w/ accompanying non-optimizing macro.

This is intended for security-conscious applications.

@param

rdi: is dest
rsi: is the number of bytes to set

@return

@see libc/str/explicit_bzero.S

expm1

Returns 𝑒^𝑥-𝟷.

@param

double x

@return

double

@see libc/tinymath/expm1.c

expm1f

Returns 𝑒^x-1.

@param

𝑥: is float scalar in low quarter of %xmm0

@return

: float scalar in low quarter of %xmm0

@see libc/tinymath/expm1f.S

expm1l

Returns 𝑒^𝑥-𝟷.

@param

𝑥: is an 80-bit long double passed on stack in 16-bytes

@return

: result of exponentiation on FPU stack in %st

@see libc/tinymath/expm1l.S

_extend

Extends static allocation.

This simple fixed allocator has unusual invariants

!(p & 0xffff) && !(((p >> 3) + 0x7fff8000) & 0xffff)

which must be the case when selecting a starting address. We also make the assumption that allocations can only grow monotonically. Furthermore allocations shall never be removed or relocated.

@param

void* p: points to start of memory region
unsigned long n: specifies how many bytes are needed
void* e: points to end of memory that's allocated
int f: should be MAP_PRIVATE or MAP_SHARED
long h: is highest address to which e may grow

@return

void*: new value for e or null w/ errno

@raise ENOMEM if we require more vespene gas

@see libc/intrin/extend.c

_f2ld2

Thunks float(*fn)(float,float) -> long double fn.

@param

%xmm0[0]: contains float param

@return

: %xmm0[0] contains float result

@note 100% negligible overhead

@see libc/tinymath/f2ld2.S

fabs

Returns absolute value of 𝑥.

@param

𝑥: is double passed in lower half on %xmm0

@return

: absolute value in %xmm0

@see libc/tinymath/fabs.S

fabsf

Returns absolute value of 𝑥.

@param

𝑥: is float passed in lower quarter on %xmm0

@return

: absolute value in %xmm0

@see libc/tinymath/fabsf.S

fabsl

Returns absolute value of 𝑥.

@param

𝑥: long double passed on stack

@return

: absolute value in %st

@see libc/tinymath/fabsl.S

faccessat

Checks if effective user can access path in particular ways.

@param

int dirfd: is normally AT_FDCWD but if it's an open directory and file is a relative path, then file is opened relative to dirfd
const char* path: is a filename or directory
int amode: can be R_OK, W_OK, X_OK, or F_OK
int flags: can have AT_EACCESS and/or AT_SYMLINK_NOFOLLOW

@return

int: 0 if ok, or -1 and sets errno

@raise EINVAL if mode has bad value

@raise EPERM if pledge() is in play without rpath promise

@raise EACCES if access for requested mode would be denied

@raise ENOTDIR if a directory component in path exists as non-directory

@raise ENOENT if component of path doesn't exist or path is empty

@raise ENOTSUP if path is a zip file and dirfd isn't AT_FDCWD

@note on Linux flags is only supported on Linux 5.8+

@asyncsignalsafe

@see libc/calls/faccessat.c

fadvise

Drops hints to O/S about intended I/O behavior.

It makes a huge difference. For example, when copying a large file, it can stop the system from persisting GBs of useless memory content.

@param

int fd
unsigned long offset
unsigned long len: 0 means until end of file
int advice: can be MADV_SEQUENTIAL, MADV_RANDOM, etc.

@return

int: 0 on success, or -1 w/ errno

@raise EBADF if fd isn't a valid file descriptor

@raise ESPIPE if fd refers to a pipe

@raise EINVAL if advice was invalid

@raise ENOSYS on XNU and OpenBSD

@see libc/calls/fadvise.c

__fbufsize

Returns capacity of stdio stream buffer.

@param

struct FILE* f

@return

unsigned long

@see libc/stdio/fbufsize.c

fchdir

Sets current directory based on file descriptor.

This does *not* update the PWD environment variable.

@param

int dirfd

@return

int

@see open(path, O_DIRECTORY)

@asyncsignalsafe

@see libc/calls/fchdir.c

fchmod

Changes file permissions via open()'d file descriptor.

@param

int fd
unsigned int mode: contains octal flags (base 8)

@return

int

@asyncsignalsafe

@see chmod()

@see libc/calls/fchmod.c

fchmodat

Changes permissions on file, e.g.:

CHECK_NE(-1, fchmodat(AT_FDCWD, "foo/bar.txt", 0644));
CHECK_NE(-1, fchmodat(AT_FDCWD, "o/default/program.com", 0755));
CHECK_NE(-1, fchmodat(AT_FDCWD, "privatefolder/", 0700));

@param

int dirfd
const char* path: must exist
unsigned int mode: contains octal flags (base 8)
int flags: can have AT_SYMLINK_NOFOLLOW

@return

int

@raise ENOTSUP if dirfd or path use zip file system

@errors ENOENT, ENOTDIR, ENOSYS

@asyncsignalsafe

@see fchmod()

@see libc/calls/fchmodat.c

fchown

Changes owner and/or group of file, via open()'d descriptor.

@param

int fd
unsigned int uid: is user id, or -1u to not change
unsigned int gid: is group id, or -1u to not change

@return

int: 0 on success, or -1 w/ errno

@see /etc/passwd for user ids

@see /etc/group for group ids

@raises ENOSYS on Windows

@see libc/calls/fchown.c

fchownat

Changes owner and/or group of path.

@param

int dirfd: is open()'d relative-to directory, or AT_FDCWD, etc.
const char* path
unsigned int uid: is user id, or -1 to not change
unsigned int gid: is group id, or -1 to not change
int flags: can have AT_SYMLINK_NOFOLLOW, etc.

@return

int: 0 on success, or -1 w/ errno

@raise ENOTSUP if dirfd or path use zip file system

@see chown(), lchown() for shorthand notation

@see /etc/passwd for user ids

@see /etc/group for group ids

@asyncsignalsafe

@see libc/calls/fchownat.c

fclose

Closes standard i/o stream and its underlying thing.

@param

struct FILE* f: is the file object

@return

int: 0 on success or -1 on error, which can be a trick for differentiating between EOF and real errors during previous i/o calls, without needing to call ferror()

@see libc/stdio/fclose.c

fclose_s

@param

struct FILE** fp

@return

int

@see libc/stdio/fclose_s.c

fcntl

Does things with file descriptor, e.g.

CHECK_NE(-1, fcntl(fd, F_SETFD, FD_CLOEXEC));

This function lets you duplicate file descriptors without running into an edge case where they take over stdio handles:

CHECK_GE((newfd = fcntl(oldfd, F_DUPFD,         3)), 3);
CHECK_GE((newfd = fcntl(oldfd, F_DUPFD_CLOEXEC, 3)), 3);

This function implements file record locking, which lets independent processes (and on Linux 3.15+, threads too!) lock arbitrary ranges associated with a file. See test/libc/calls/lock_test.c and other locking related tests in that folder.

On Windows, the Cosmopolitan Libc polyfill for POSIX advisory locks only implements enough of its nuances to support SQLite's needs. Some possibilities, e.g. punching holes in lock, will raise ENOTSUP.

@param

int fd

is the file descriptor

int cmd

can be one of:

F_GETFD gets FD_CLOEXEC status of fd
F_SETFD sets FD_CLOEXEC status of argfile descriptor
F_GETFLreturns file descriptor status flags
F_SETFLsets file descriptor status flags
F_DUPFD is like dup() but argis a minimum result, e.g. 3
F_DUPFD_CLOEXEC ditto but sets O_CLOEXECon returned fd
F_SETLK for record locking where arg is struct flock *
F_SETLKWditto but waits for lock (SQLite avoids this)
F_GETLKto retrieve information about a record lock
F_OFD_SETLKfor better non-blocking lock (Linux 3.15+ only)
F_OFD_SETLKWfor better blocking lock (Linux 3.15+ only)
F_OFD_GETLKfor better lock querying (Linux 3.15+ only)
F_FULLFSYNCon MacOS for fsync() with release barrier
F_BARRIERFSYNCon MacOS for fsync() with even more barriers
F_SETNOSIGPIPE on MacOS and NetBSD to control SIGPIPE
F_GETNOSIGPIPE on MacOS and NetBSD to control SIGPIPE
F_GETPATH on MacOS and NetBSD where arg is char[PATH_MAX]
F_MAXFDon NetBSD to get max open file descriptor
F_NOCACHEon MacOS to toggle data caching
F_GETPIPE_SZon Linux to get pipe size
F_SETPIPE_SZon Linux to set pipe size
F_NOTIFY raise SIGIO upon fd events in arg(Linux only) -DN_ACCESSfor file access -DN_MODIFYfor file modifications -DN_CREATEfor file creations -DN_DELETEfor file deletions -DN_RENAMEfor file renames -DN_ATTRIBfor file attribute changes -DN_MULTISHOT bitwise or for realtime signals (non-coalesced)

...

@return

int: 0 on success, or -1 w/ errno

@raise EBADF if fd isn't a valid open file descriptor

@raise EINVAL if cmd is unknown or unsupported by os

@raise EINVAL if cmd is invalid or unsupported by os

@raise EPERM if pledge() is in play w/o stdio or flock promise

@raise ENOLCK if F_SETLKW would have exceeded RLIMIT_LOCKS

@raise EPERM if cmd is F_SETOWN and we weren't authorized

@raise ESRCH if cmd is F_SETOWN and process group not found

@raise ENOTSUP on Windows if locking operation isn't supported yet

@raise EDEADLK if cmd was F_SETLKW and waiting would deadlock

@raise EMFILE if cmd is F_DUPFD or F_DUPFD_CLOEXEC and RLIMIT_NOFILE would be exceeded

@cancellationpoint when cmd is F_SETLKW or F_OFD_SETLKW

@asyncsignalsafe

@restartable

@see libc/calls/fcntl.c

fcvt

@param

double value
int ndigit
int* decpt
int* sign

@return

char*

@see libc/stdio/ecvt.c

fdatasync

Blocks until kernel flushes non-metadata buffers for fd to disk.

@param

int fd

@return

int: 0 on success, or -1 w/ errno

@see sync(), fsync(), sync_file_range()

@see __nosync to secretly disable

@raise ECANCELED if thread was cancelled in masked mode

@raise EINTR if signal was delivered

@cancellationpoint

@asyncsignalsafe

@see libc/calls/fdatasync.c

fdim

Returns positive difference.

@param

double x
double y

@return

double

@see libc/tinymath/fdim.c

fdimf

Returns positive difference.

@param

float x
float y

@return

float

@see libc/tinymath/fdimf.c

fdiml

Returns positive difference.

@param

long double x
long double y

@return

long double

@see libc/tinymath/fdiml.c

fdopen

Allocates stream object for already-opened file descriptor.

@param

int fd: existing file descriptor or -1 for plain old buffer
const char* mode: is passed to fopenflags()

@return

struct FILE*: new stream or NULL w/ errno

@error ENOMEM

@see libc/stdio/fdopen.c

fdopendir

Creates directory object for file descriptor.

@param

int fd: gets owned by this function, if it succeeds

@return

struct dirstream*: new directory object, which must be freed by closedir(), or NULL w/ errno

@errors ENOMEM and fd is closed

@see libc/stdio/dirstream.c

fegetround

Returns rounding mode.

This implementation retrieves it from the x87 FPU control word.

@return

int

@see fesetround() for changing this

@see libc/runtime/fegetround.c

fentry

Function entry hook stub.

@return

@note cc -pg -mfentry adds this to the start of every function

@see libc/log/shadowargs.ncabi.c

@mode long,legacy,real

@see libc/nexgen32e/fentry.S

feof

Returns true if stream is in end-of-file state.

@param

struct FILE* f: is file object stream pointer

@return

int

@see feof_unlocked()

@threadsafe

@see libc/stdio/feof.c

feof_unlocked

Returns true if stream is in end-of-file state.

@param

struct FILE* f: is file object stream pointer

@return

int

@see feof()

@see libc/stdio/feof_unlocked.c

ferror

Returns nonzero if stream is in error state.

@param

struct FILE* f: is file stream pointer

@return

int: non-zero if and only if it's an error state

@see ferror_unlocked(), feof()

@note EOF doesn't count

@threadsafe

@see libc/stdio/ferror.c

ferror_unlocked

Returns nonzero if stream is in error state.

@param

struct FILE* f: is file stream pointer

@return

int: non-zero w/ errno only if f is in error state

@note EOF doesn't count

@see ferror(), feof()

@see libc/stdio/ferror_unlocked.c

fesetround

Sets rounding mode.

This configures the x87 FPU as well as SSE.

@param

int mode: may be FE_TONEAREST, FE_DOWNWARD, FE_UPWARD, or FE_TOWARDZERO

@return

int: 0 on success, or -1 on error

@see libc/runtime/fesetround.c

fexecve

Executes binary executable at file descriptor.

This is only supported on Linux and FreeBSD. APE binaries are supported.

@param

int fd: is opened executable and current file position is ignored
char** argv
char** envp

@return

int: doesn't return on success, otherwise -1 w/ errno

@raise ENOEXEC if file at fd isn't an assimilated ELF executable

@raise ENOSYS on Windows, XNU, OpenBSD, NetBSD, and Metal

@see libc/calls/fexecve.c

fflush

Blocks until data from stream buffer is written out.

@param

struct FILE* f: is the stream handle, or 0 for all streams

@return

int: is 0 on success or -1 on error

@threadsafe

@see libc/stdio/fflush.c

fflush_unlocked

Blocks until data from stream buffer is written out.

@param

struct FILE* f: is the stream handle, or 0 for all streams

@return

int: is 0 on success or -1 on error

@see libc/stdio/fflush_unlocked.c

ffs

Finds lowest set bit in word.

  uint32 𝑥   bsf(𝑥) tzcnt(𝑥)   ffs(𝑥)   bsr(𝑥) lzcnt(𝑥)
0x00000000      wut       32        0      wut       32
0x00000001        0        0        1        0       31
0x80000001        0        0        1       31        0
0x80000000       31       31       32       31        0
0x00000010        4        4        5        4       27
0x08000010        4        4        5       27        4
0x08000000       27       27       28       27        4
0xffffffff        0        0        1       31        0

@param

edi: is the input number

@return

: number in range [1,32] or 0 if no bits set

@see also treasure trove of nearly identical functions

@asyncsignalsafe

@see libc/nexgen32e/ffs.S

ffsl

Finds lowest set bit in word.

  uint32 𝑥   bsf(𝑥) tzcnt(𝑥)   ffs(𝑥)   bsr(𝑥) lzcnt(𝑥)
0x00000000      wut       32        0      wut       32
0x00000001        0        0        1        0       31
0x80000001        0        0        1       31        0
0x80000000       31       31       32       31        0
0x00000010        4        4        5        4       27
0x08000010        4        4        5       27        4
0x08000000       27       27       28       27        4
0xffffffff        0        0        1       31        0

@param

rdi: is the input number

@return

: number in range [1,64] or 0 if no bits set

@see also treasure trove of nearly identical functions

@asyncsignalsafe

@see libc/nexgen32e/ffsl.S

ffsll

Finds lowest set bit in word.

  uint32 𝑥   bsf(𝑥) tzcnt(𝑥)   ffs(𝑥)   bsr(𝑥) lzcnt(𝑥)
0x00000000      wut       32        0      wut       32
0x00000001        0        0        1        0       31
0x80000001        0        0        1       31        0
0x80000000       31       31       32       31        0
0x00000010        4        4        5        4       27
0x08000010        4        4        5       27        4
0x08000000       27       27       28       27        4
0xffffffff        0        0        1       31        0

@param

rdi: is the input number

@return

: number in range [1,64] or 0 if no bits set

@see also treasure trove of nearly identical functions

@asyncsignalsafe

@see libc/nexgen32e/ffsl.S

fgetc

Reads byte from stream.

@param

struct FILE* f: is non-null file object stream pointer

@return

int: byte in range 0..255, or -1 w/ errno

@see fgetc_unlocked()

@threadsafe

@see libc/stdio/fgetc.c

fgetc_unlocked

Reads byte from stream.

@param

struct FILE* f: is file object stream pointer

@return

int: byte in range 0..255, or -1 w/ errno

@see fgetc()

@see libc/stdio/fgetc_unlocked.c

fgetln

Retrieves line from stream, e.g.

char *line;
while ((line = _chomp(fgetln(stdin, 0)))) {
  printf("%s\n", line);
}

The returned memory is owned by the stream. It'll be reused when fgetln() is called again. It's free()'d upon fclose() / fflush()

@param

struct FILE* stream: specifies non-null open input stream
unsigned long* len: optionally receives byte length of line

@return

char*: nul-terminated line string, including the \n character unless a line happened before EOF without \n, otherwise it returns NULL and feof() and ferror() can examine the state

@see getdelim()

@see libc/stdio/fgetln.c

fgetpos

@param

struct FILE* stream
unsigned long* pos

@return

int

@see libc/stdio/fgetpos.c

fgets

Reads line from stream.

This function is similar to getline() except it'll truncate lines exceeding size. The line ending marker is included and may be removed using _chomp().

@param

char* s: is output buffer
int size: is capacity of s
struct FILE* f: is non-null file object stream pointer

@return

char*: s on success, NULL on error, or NULL if EOF happens when zero characters have been read

@see fgets_unlocked()

@threadsafe

@see libc/stdio/fgets.c

fgets_unlocked

Reads line from stream.

This function is similar to getline() except it'll truncate lines exceeding size. The line ending marker is included and may be removed using _chomp().

@param

char* s: is output buffer
int size: is capacity of s
struct FILE* f: is non-null file object stream pointer

@return

char*: s on success, NULL on error, or NULL if EOF happens when zero characters have been read

@see libc/stdio/fgets_unlocked.c

fgetwc

Reads UTF-8 character from stream.

@param

struct FILE* f: is non-null file object stream pointer

@return

unsigned int: wide character or -1 on EOF or error

@see fgetwc_unlocked()

@threadsafe

@see libc/stdio/fgetwc.c

fgetwc_unlocked

Reads UTF-8 character from stream.

@param

struct FILE* f

@return

unsigned int: wide character or -1 on EOF or error

@see libc/stdio/fgetwc_unlocked.c

fgetws

Reads UTF-8 content from stream into UTF-32 buffer.

This function is similar to getline() except it'll truncate lines exceeding size. The line ending marker is included and may be removed using _chomp().

@param

int* s: is is nul-terminated string that's non-null
int size: is byte length of s
struct FILE* f: is file stream object pointer

@return

int*

@see fgetws()

@threadsafe

@see libc/stdio/fgetws.c

fgetws_unlocked

Reads UTF-8 content from stream into UTF-32 buffer.

This function is similar to getline() except it'll truncate lines exceeding size. The line ending marker is included and may be removed using _chomp().

@param

int* s: is is nul-terminated string that's non-null
int size: is byte length of s
struct FILE* f: is file stream object pointer

@return

int*

@see fgetws()

@see libc/stdio/fgetws_unlocked.c

fileexists

Returns true if file exists at path.

This function is equivalent to:

struct stat st;
return stat(path, &st) != -1;

Please note that things which aren't strictly files, e.g. directories or sockets, could be considered files for the purposes of this function. The stat() function may be used to differentiate them.

@param

const char* path

@return

_Bool

@see libc/calls/fileexists.c

fileno

Returns file descriptor associated with stream.

@param

struct FILE* f: is file stream object pointer

@return

int: fd on success or -1 w/ errno;

@threadsafe

@see libc/stdio/fileno.c

fileno_unlocked

Returns file descriptor associated with stream.

@param

struct FILE* f: is file stream object pointer

@return

int: fd on success or -1 w/ errno;

@see libc/stdio/fileno_unlocked.c

FindClose

Finds more files in directory.

@param

long hFindFile

@return

int

@note this wrapper takes care of ABI, STRACE(), and __winerr()

@see libc/intrin/findclose.c

FindComBinary

Returns path of binary without debug information, or null.

@return

const char*: path to non-debug binary, or -1 w/ errno

@see libc/runtime/findcombinary.c

FindContentType

Returns Content-Type for file extension.

@param

const char* p
unsigned long n

@return

const char*

@see net/http/findcontenttype.c

FindDebugBinary

Returns path of binary with the debug information, or null.

@return

const char*: path to debug binary, or NULL

@see libc/runtime/finddebugbinary.c

FindEmbeddedApe

Returns offset of binary embedded inside binary.

This can be used to load zip assets from an executable that hasn't gone through the objcopy -S -O binary step. We make the assumption that an x86_64-pc-linux-gnu toolchain is being used. This routine would need to be changed to accommodate binaries built locally on Apple, FreeBSD, etc.

@param

const unsigned char* p: needs to be page aligned
unsigned long n: is byte length of p

@return

unsigned char*: base address of image or NULL if not found

@see libc/str/findembeddedape.c

FindFirstFile

Finds first file in directory.

@param

const unsigned short* lpFileName
struct NtWin32FindData* out_lpFindFileData

@return

long

@note this wrapper takes care of ABI, STRACE(), and __winerr()

@see libc/intrin/findfirstfile.c

FindMemoryInterval

@param

struct _mmi* mm
int x

@return

unsigned int

@see libc/intrin/findmemoryinterval.c

FindNextFile

Finds more files in directory.

@param

long hFindFile
struct NtWin32FindData* out_lpFindFileData

@return

int

@note this wrapper takes care of ABI, STRACE(), and __winerr()

@see libc/intrin/findnextfile.c

finite

Returns nonzero if 𝑥 isn't INFINITY or NAN.

@param

double x

@return

int

@see libc/tinymath/finite.c

finitef

Returns nonzero if 𝑥 isn't INFINITY or NAN.

@param

float x

@return

int

@see libc/tinymath/finitef.c

finitel

Returns nonzero if 𝑥 isn't INFINITY or NAN.

@param

long double x

@return

int

@see libc/tinymath/finitel.c

FixPath

@param

char* path

@return

void

@see libc/runtime/getdosenviron.c

__fixupnewsockfd

Applies non-atomic file descriptor fixups on XNU or ancient Linux.

@param

int fd: of -1 means no-op
int flags

@return

int

@see libc/sock/fixupnewsockfd.c

__flbf

Returns nonzero if stream is line buffered.

@param

struct FILE* f

@return

int

@see libc/stdio/flbf.c

flock

Acquires lock on file.

Please note multiple file descriptors means multiple locks.

@param

int fd
int op: can have LOCK_{SH,EX,NB,UN} for shared, exclusive, non-blocking, and unlocking

@return

int: 0 on success, or -1 w/ errno

@cancellationpoint

@restartable

@see libc/calls/flock.c

flock2cosmo

@param

unsigned long memory

@return

void

@see libc/calls/metaflock.c

flockfile

Acquires reentrant lock on stdio object, blocking if needed.

@param

struct FILE* f

@return

void

@see libc/stdio/flockfile.c

flogf

Writes formatted message w/ timestamp to log.

@param

unsigned int level
const char* file
int line
struct FILE* f
const char* fmt
...

@return

void

@see vflogf()

@see libc/log/flogf.c

floor

@param

double x

@return

double

@see libc/tinymath/floor.c

floorf

@param

float x

@return

float

@see libc/tinymath/floorf.c

floorl

Returns largest integral not greater than 𝑥.

@param

𝑥: is long double passed on stack

@return

: float scalar in low quarter of %xmm0

@see libc/tinymath/floorl.S

FlushFileBuffers

Flushes buffers of specified file to disk.

This provides a stronger degree of assurance and blocking for things to be sent to a physical medium, but it's not guaranteed unless your file is opened in a direct non-caching mode. One main advantage here seems to be coherency.

@param

long hFile

@return

int

@note this wrapper takes care of ABI, STRACE(), and __winerr()

@note consider buying a ups

@see FlushViewOfFile()

@see libc/intrin/flushfilebuffers.c

_flushlbf

Flushes all line-buffered streams.

@return

void

@see libc/stdio/flushlbf.c

FlushViewOfFile

Syncs memory created by MapViewOfFileEx().

This doesn't wait until the pages are written out to the physical medium. This doesn't update timestamps or file/dir metadata.

@param

void* lpBaseAddress
unsigned long dwNumberOfBytesToFlush

@return

int

@note this wrapper takes care of ABI, STRACE(), and __winerr()

@note consider buying a ups

@see FlushFileBuffers()

@see libc/intrin/flushviewoffile.c

fma

@param

double x
double y
double z

@return

double

@see libc/tinymath/fma.c

fmax

Returns maximum of two doubles.

If one argument is NAN then the other is returned. This function is designed to do the right thing with signed zeroes.

@param

double x
double y

@return

double

@see libc/tinymath/fmax.c

fmaxf

Returns maximum of two floats.

If one argument is NAN then the other is returned. This function is designed to do the right thing with signed zeroes.

@param

float x
float y

@return

float

@see libc/tinymath/fmaxf.c

fmaxl

Returns maximum of two long doubles.

If one argument is NAN then the other is returned. This function is designed to do the right thing with signed zeroes.

@param

long double x
long double y

@return

long double

@see libc/tinymath/fmaxl.c

fmemopen

Opens buffer as stream.

@param

void* buf: becomes owned by this function, and is allocated if NULL
unsigned long size
const char* mode

@return

struct FILE*: new stream or NULL w/ errno

@raise ENOMEM if buf is NULL and we failed to allocate it

@raise ENOMEM if buf is NULL and malloc() wasn't linked

@raise EINVAL if buf is NULL when + isn't in mode

@see libc/stdio/fmemopen.c

fmin

Returns minimum of two doubles.

If one argument is NAN then the other is returned. This function is designed to do the right thing with signed zeroes.

@param

double x
double y

@return

double

@see libc/tinymath/fmin.c

fminf

Returns minimum of two floats.

If one argument is NAN then the other is returned. This function is designed to do the right thing with signed zeroes.

@param

float x
float y

@return

float

@see libc/tinymath/fminf.c

fminl

Returns minimum of two long doubles.

If one argument is NAN then the other is returned. This function is designed to do the right thing with signed zeroes.

@param

long double x
long double y

@return

long double

@see libc/tinymath/fminl.c

fmod

fmod [sic] does (𝑥 rem 𝑦) w/ round()-style rounding.

@param

𝑥: is double passed in lower half of %xmm0
𝑦: is double passed in lower half of %xmm1

@return

: remainder ∈ (-|𝑦|,|𝑦|) in %xmm0

@define 𝑥-trunc(𝑥/𝑦)*𝑦

@see emod()

@see libc/tinymath/fmod-tiny.S

fmodl

fmod [sic] does (𝑥 rem 𝑦) w/ round()-style rounding.

@param

𝑥: is an 80-bit long double passed on stack in 16-bytes
𝑦: is the power, also pushed on stack, in reverse order

@return

: remainder ∈ (-|𝑦|,|𝑦|) in %st

@define 𝑥-truncl(𝑥/𝑦)*𝑦

@see emod()

@see libc/calls/fmodl.S

__fmt

Implements {,v}{,s{,n},{,{,x}as},f,d}printf domain-specific language.

Type Specifiers

%s char * (thompson-pike unicode)
%ls wchar_t * (32-bit unicode → thompson-pike unicode)
%hs char16_t * (16-bit unicode → thompson-pike unicode)
%b int (radix 2 binary)
%o int (radix 8 octal)
%d int (radix 10 decimal)
%x int (radix 16 hexadecimal)
%X int (radix 16 hexadecimal uppercase)
%p pointer (48-bit hexadecimal)
%u unsigned
%g double (smart formatting)
%e double (expo formatting)
%f double (ugly formatting)
%a double (hex formatting)
%Lg long double

Size Modifiers

%hhd char (8-bit)
%hd short (16-bit)
%ld long (64-bit)
%lu unsigned long (64-bit)
%lx unsigned long (64-bit hexadecimal)
%jd intmax_t (64-bit)
%jjd int128_t (128-bit)

Width Modifiers

%08d fixed columns w/ zero leftpadding
%8d fixed columns w/ space leftpadding
%*s variable column string (thompson-pike)

Precision Modifiers

%.8s supplied byte length (obeys nul terminator)
%.*s supplied byte length argument (obeys nul terminator)
%`.*s supplied byte length argument c escaped (ignores nul term)
%#.*s supplied byte length argument visualized (ignores nul term)
%.*hs supplied char16_t length argument (obeys nul terminator)
%.*ls supplied wchar_t length argument (obeys nul terminator)

Formatting Modifiers

%,d thousands separators
%'s escaped c string literal
%`c c escaped character
%`'c c escaped character quoted
%`s c escaped string
%`'s c escaped string quoted
%`s escaped double quoted c string literal
%`c escaped double quoted c character literal
%+d plus leftpad if positive (aligns w/ negatives)
% d space leftpad if positive (aligns w/ negatives)
%#s datum (radix 256 null-terminated ibm cp437)
%#x int (radix 16 hexadecimal w/ 0x prefix if not zero)

@param

void* fn
void* arg
const char* format
struct __va_list* va

@return

int

@note implementation detail of printf(), snprintf(), etc.

@see printf() for wordier documentation

@note netlib.org is so helpful

@asyncsignalsafe if floating point isn't used

@vforksafe if floating point isn't used

@see libc/fmt/fmt.c

__fmt_stoa

Converts string to array.

This is used by __fmt() to implement the %s and %c directives. The content outputted to the array is always UTF-8, but the input may be UTF-16 or UTF-32.

@param

int(*)() out
void* arg
void* data
unsigned long flags
unsigned long precision
unsigned long width
unsigned char signbit
unsigned char qchar

@return

int

@see __fmt()

@see libc/fmt/stoa.c

fnmatch

Matches filename.

* for wildcard
? for single character
[abc] to match character within set
[!abc] to match character not within set
\*\?\[\] for escaping above special syntax

@param

const char* pat
const char* str
int flags

@return

int

@see glob()

@see third_party/musl/fnmatch.c

FoldHeader

Collapses repeating headers onto a single line.

@param

struct HttpMessage* msg
char* b
int h
unsigned long* z

@return

char*

@see net/http/foldheader.c

fopen

Opens file as stream object.

@param

const char* pathname: is a utf-8 ideally relative filename
const char* mode: is the string mode/flag DSL see fopenflags()

@return

struct FILE*: new object to be free'd by fclose() or NULL w/ errno

@note microsoft unilaterally deprecated this function lool

@see libc/stdio/fopen.c

fopenflags

Turns stdio flags description string into bitmask.

@param

const char* mode

@return

int

@see libc/stdio/fopenflags.c

fork

Creates new process.

@return

int: 0 to child, child pid to parent, or -1 w/ errno

@raise EAGAIN if RLIMIT_NPROC was exceeded or system lacked resources

@raise ENOMEM if we require more vespene gas

@asyncsignalsafe

@threadsafe

@see libc/runtime/fork.c

FormatBinary64

Converts unsigned 64-bit integer to binary string.

@param

char* p: needs at least 67 bytes
unsigned long x
char z: is 0 for DIGITS, 1 for 0bDIGITS, 2 for 0bDIGITS if ≠0

@return

char*: pointer to nul byte

@see libc/fmt/formatbinary64.c

FormatFlex64

Formats integer using decimal or hexadecimal.

This formats as int64 signed decimal. However it's a:

positive number
with population count of 1
and a magnitude of at least 256

Then we switch to hex notation to make the number more readable.

@param

char* p
long x
char z

@return

char*

@see libc/fmt/formatflex64.c

FormatHex64

Converts unsigned 64-bit integer to hex string.

@param

char* p: needs at least 19 bytes
unsigned long x
char z: is 0 for DIGITS, 1 for 0xDIGITS, 2 for 0xDIGITS if ≠0

@return

char*: pointer to nul byte

@see libc/fmt/formathex64.c

FormatHttpDateTime

Formats HTTP timestamp, e.g.

Sun, 04 Oct 2020 19:50:10 GMT

This function is the same as:

strftime(p, 30, "%a, %d %b %Y %H:%M:%S %Z", tm)

Except this function goes 10x faster:

FormatHttpDateTime  l:        25𝑐         8𝑛𝑠
strftime            l:       709𝑐       229𝑛𝑠

@param

char* p
struct tm* tm: must be zulu see gmtime_r() and nowl()

@return

char*

@see ParseHttpDateTime()

@see net/http/formathttpdatetime.c

FormatInt32

Converts signed 32-bit integer to string.

@param

char* p: needs at least 12 bytes
int x

@return

char*: pointer to nul byte

@see libc/intrin/formatint32.c

FormatInt64

Converts signed 64-bit integer to string.

@param

char* p: needs at least 21 bytes
long x

@return

char*: pointer to nul byte

@see libc/intrin/formatint64.c

FormatInt64Thousands

Converts 64-bit integer to string w/ commas.

@param

char* p: needs at least 27 bytes
long x

@return

char*: pointer to nul byte

@see libc/fmt/formatint64thousands.c

FormatOctal32

Converts unsigned 32-bit integer to octal string.

@param

char* p: needs at least 12 bytes
unsigned int x
_Bool z: ensures it starts with zero

@return

char*: pointer to nul byte

@see libc/fmt/formatoctal32.c

FormatOctal64

Converts unsigned 64-bit integer to octal string.

@param

char* p: needs at least 24 bytes
unsigned long x
_Bool z: ensures it starts with zero

@return

char*: pointer to nul byte

@see libc/fmt/formatoctal64.c

FormatUint32

Converts unsigned 32-bit integer to string.

@param

char* p: needs at least 12 bytes
unsigned int x

@return

char*: pointer to nul byte

@see libc/intrin/formatint32.c

FormatUint64

Converts unsigned 64-bit integer to string.

@param

char* p: needs at least 21 bytes
unsigned long x

@return

char*: pointer to nul byte

@see libc/intrin/formatint64.c

FormatUint64Thousands

Converts unsigned 64-bit integer to string w/ commas.

@param

char* p: needs at least 27 bytes
unsigned long x

@return

char*: pointer to nul byte

@see libc/fmt/formatint64thousands.c

fpathconf

@param

int fd
int name

@return

long

@see libc/runtime/fpathconf.c

__fpending

Returns number of pending output bytes.

@param

struct FILE* f

@return

unsigned long

@see libc/stdio/fpending.c

fprintf

Formats and writes text to stream.

@param

struct FILE* f
const char* fmt
...

@return

int

@see printf() for further documentation

@see libc/stdio/fprintf.c

fprintf_unlocked

Formats and writes text to stream.

@param

struct FILE* f
const char* fmt
...

@return

int

@see printf() for further documentation

@see libc/stdio/fprintf_unlocked.c

__fpurge

Discards contents of stream buffer.

@param

struct FILE* f

@return

void

@see libc/stdio/__fpurge.c

fpurge

Discards contents of stream buffer.

@param

struct FILE* f

@return

int

@see libc/stdio/fpurge.c

fputc

Writes byte to stream.

@param

int c: is byte to buffer or write, which is masked
struct FILE* f

@return

int: c as unsigned char if written or -1 w/ errno

@threadsafe

@see libc/stdio/fputc.c

fputc_unlocked

Writes byte to stream.

@param

int c: is byte to buffer or write, which is masked
struct FILE* f

@return

int: c as unsigned char if written or -1 w/ errno

@see libc/stdio/fputc_unlocked.c

fputs

Writes string to stream.

Writing stops at the NUL-terminator, which isn't included in output. This function blocks until the full string is written, unless an unrecoverable error happens.

@param

const char* s: is a NUL-terminated string that's non-NULL
struct FILE* f: is an open stream

@return

int: bytes written, or -1 w/ errno

@threadsafe

@see libc/stdio/fputs.c

fputs_unlocked

Writes string to stream.

Writing stops at the NUL-terminator, which isn't included in output. This function blocks until the full string is written, unless an unrecoverable error happens.

@param

const char* s: is a NUL-terminated string that's non-NULL
struct FILE* f: is an open stream

@return

int: bytes written, or -1 w/ errno

@see libc/stdio/fputs_unlocked.c

fputwc

Writes wide character to stream.

@param

int wc: has wide character
struct FILE* f: is file object stream pointer

@return

unsigned int: wide character if written or -1 w/ errno

@threadsafe

@see libc/stdio/fputwc.c

fputwc_unlocked

Writes wide character to stream.

@param

int wc: has wide character
struct FILE* f: is file object stream pointer

@return

unsigned int: wide character if written or -1 w/ errno

@see libc/stdio/fputwc_unlocked.c

fputws

Writes wide character string to stream.

Writing stops at the NUL-terminator, which isn't included in output. This function blocks until the full string is written, unless an unrecoverable error happens.

@param

const int* s: is a NUL-terminated string that's non-NULL
struct FILE* f: is an open stream

@return

int: strlen(s), or -1 w/ errno

@threadsafe

@see libc/stdio/fputws.c

fputws_unlocked

Writes wide character string to stream.

Writing stops at the NUL-terminator, which isn't included in output. This function blocks until the full string is written, unless an unrecoverable error happens.

@param

const int* s: is a NUL-terminated string that's non-NULL
struct FILE* f: is an open stream

@return

int: strlen(s), or -1 w/ errno

@see libc/stdio/fputws_unlocked.c

fread

Reads data from stream.

@param

void* buf
unsigned long stride: specifies the size of individual items
unsigned long count: is the number of strides to fetch
struct FILE* f

@return

unsigned long: count on success, [0,count) on eof, or 0 on error or count==0

@threadsafe

@see libc/stdio/fread.c

fread_unlocked

Reads data from stream.

@param

void* buf
unsigned long stride: specifies the size of individual items
unsigned long count: is the number of strides to fetch
struct FILE* f

@return

unsigned long: count on success, [0,count) on eof, or 0 on error or count==0

@see libc/stdio/fread_unlocked.c

__freadable

Returns nonzero if stream allows reading.

@param

struct FILE* f

@return

int

@see libc/stdio/freadable.c

__freading

Returns nonzero if stream is read only.

@param

struct FILE* f

@return

int

@see libc/stdio/freading.c

free

Free memory returned by malloc() & co.

Releases the chunk of memory pointed to by p, that had been previously allocated using malloc or a related routine such as realloc. It has no effect if p is null. If p was not malloced or already freed, free(p) will by default cause the current program to abort.

@param

rdi: is allocation address, which may be NULL

@return

@see dlfree()

@threadsafe

@see libc/mem/free.S

free_s

@param

void* v

@return

void

@see libc/runtime/free_s.c

freeaddrinfo

Frees addresses returned by getaddrinfo().

@param

struct addrinfo* ai

@return

void

@threadsafe

@see libc/dns/freeaddrinfo.c

freedtoa

@param

char* s

@return

void

@see third_party/gdtoa/dmisc.c

FreeHostsTxt

Frees HOSTS.TXT data structure populated by ParseHostsTxt().

@param

struct HostsTxt** ht

@return

void

@see libc/dns/freehoststxt.c

freelocale

@param

struct __locale_struct* l

@return

void

@see libc/str/freelocale.c

FreeResolvConf

Frees resolv.conf data structure populated by ParseResolvConf().

@param

struct ResolvConf** rvp

@return

void

@see libc/dns/freeresolvconf.c

_freestack

Frees stack.

@param

void* stk: was allocated by _mapstack()

@return

int

@see libc/runtime/mapstack.c

FreeStrList

@param

struct StrList* sl

@return

void

@see libc/stdio/freestrlist.c

freopen

Overwrites existing stream.

This function can be used in two ways. The first is sort of a mutating assignment. The second behavior, if pathname is NULL, is just changing the mode of an already open file descriptor.

@param

const char* pathname: is the file to open or NULL
const char* mode: is the mode string flags, see fopenflags()
struct FILE* stream: is the existing allocated stream memory, which is flushed and closed if already open

@return

struct FILE*: stream object if successful, or NULL w/ errno

@see libc/stdio/freopen.c

frexp

Splits number normalized fraction and exponent.

@param

double x
int* e

@return

double

@see libc/tinymath/frexp.c

frexpf

Splits number normalized fraction and exponent.

@param

float x
int* e

@return

float

@see libc/tinymath/frexpf.c

frexpl

Splits number normalized fraction and exponent.

@param

long double x
int* e

@return

long double

@see libc/tinymath/frexpl.c

fscanf

Decodes data from stream.

To read a line of data from a well-formed trustworthy file:

int x, y;
char text[256];
fscanf(f, "%d %d %s\n", &x, &y, text);

Please note that this function is brittle by default, which makes it a good fit for yolo coding. With some toil it can be used in a way that makes it reasonably hardened although getline() may be better.

@param

struct FILE* stream
const char* fmt
...

@return

int

@see libc/fmt/vcscanf.c

@see libc/stdio/fscanf.c

fseek

Repositions open file stream.

This function flushes the buffer (unless it's currently in the EOF state) and then calls lseek() on the underlying file. If the stream is in the EOF state, this function can be used to restore it without needing to reopen the file.

@param

struct FILE* f: is a non-null stream handle
long offset: is the byte delta
int whence: can be SEET_SET, SEEK_CUR, or SEEK_END

@return

int

@returns 0 on success or -1 on error

@see libc/stdio/fseek.c

fseeko

Repositions open file stream.

@param

struct FILE* f: is a non-null stream handle
long offset: is the byte delta
int whence: can be SEET_SET, SEEK_CUR, or SEEK_END

@return

int

@returns 0 on success or -1 on error

@threadsafe

@see libc/stdio/fseeko.c

fseeko_unlocked

Repositions open file stream.

@param

struct FILE* f: is a non-null stream handle
long offset: is the byte delta
int whence: can be SEET_SET, SEEK_CUR, or SEEK_END

@return

int

@returns 0 on success or -1 on error

@see libc/stdio/fseeko_unlocked.c

__fsetlocking

Does nothing and returns FSETLOCKING_INTERNAL.

@param

struct FILE* f
int type

@return

int

@see libc/stdio/fsetlocking.c

fsetpos

@param

struct FILE* stream
const unsigned long* pos

@return

int

@see libc/stdio/fsetpos.c

fstat

Returns information about file, via open()'d descriptor.

@param

int fd
struct stat* st

@return

int: 0 on success or -1 w/ errno

@raise EBADF if fd isn't a valid file descriptor

@raise EIO if an i/o error happens while reading from file system

@raise EOVERFLOW shouldn't be possible on 64-bit systems

@asyncsignalsafe

@see libc/calls/fstat.c

fstatat

Returns information about thing.

@param

int dirfd: is normally AT_FDCWD but if it's an open directory and file is a relative path, then file becomes relative to dirfd
const char* path
struct stat* st: is where result is stored
int flags: can have AT_SYMLINK_NOFOLLOW

@return

int: 0 on success, or -1 w/ errno

@see S_ISDIR(st.st_mode), S_ISREG()

@asyncsignalsafe

@vforksafe

@see libc/calls/fstatat.c

fstatfs

Returns information about filesystem.

@param

int fd
struct statfs* sf

@return

int: 0 on success, or -1 w/ errno

@cancellationpoint

@see libc/calls/fstatfs.c

fstatvfs

Returns information about filesystem.

@param

int fd
struct statvfs* sv

@return

int: 0 on success, or -1 w/ errno

@note consider using fstatfs()

@see libc/calls/fstatvfs.c

fsum

Adds doubles in array.

@param

const double* p
unsigned long n

@return

double

@see libc/tinymath/fsum.c

fsumf

Adds floats in array.

@param

const float* p
unsigned long n

@return

float

@see libc/tinymath/fsumf.c

fsync

Blocks until kernel flushes buffers for fd to disk.

@param

int fd

@return

int: 0 on success, or -1 w/ errno

@raise ECANCELED if thread was cancelled in masked mode

@raise EINTR if signal was delivered

@see fdatasync(), sync_file_range()

@see __nosync to secretly disable

@cancellationpoint

@asyncsignalsafe

@see libc/calls/fsync.c

ftell

Returns current position of stream.

@param

struct FILE* f

@return

long

@returns current byte offset from beginning, or -1 w/ errno

@see libc/stdio/ftell.c

ftello

Returns current position of stream.

@param

struct FILE* f

@return

long

@returns current byte offset from beginning, or -1 w/ errno

@threadsafe

@see libc/stdio/ftello.c

ftok

Convert pathname and a project ID to System V IPC key.

@param

const char* path
int id

@return

int

@see libc/calls/ftok.c

__ftrace

Function tracing enabled state.

After ftrace_install() has been called, the logging of C function calls may be controlled by changing this variable. If __ftrace is greater than zero, functions are logged. Otherwise, they aren't.

By convention, functions wishing to disable function tracing for a short time period should say:

void foo() {
  ftrace_enabled(-1);
  bar();
  ftrace_enabled(+1);
}

This way you still have some flexibility to force function tracing, by setting __ftrace to a higher number like 2 or 200. Even though under normal circumstances, __ftrace should only be either zero or one.

@type

int

@see libc/intrin/ftrace.c

ftrace_enabled

Changes function call logging state for current thread.

@param

int delta: is added to enabled state

@return

int: enabled state before delta was applied

@see libc/intrin/ftrace_enabled.c

ftrace_init

Enables plaintext function tracing if --ftrace flag is passed.

The --ftrace CLI arg is removed before main() is called. This code is intended for diagnostic purposes and assumes binaries are trustworthy and stack isn't corrupted. Logging plain text allows program structure to easily be visualized and hotspots identified w/ sed | sort | uniq -c | sort. A compressed trace can be made by appending --ftrace 2>&1 | gzip -4 >trace.gz to the CLI arguments.

@return

int

@see libc/runtime/_init.S for documentation

@see libc/runtime/ftraceinit.greg.c

ftrace_install

@return

int

@see libc/runtime/ftracer.c

ftracer

Prints name of function being called.

We insert CALL instructions that point to this function, in the prologues of other functions. We assume those functions behave according to the System Five NexGen32e ABI.

@return

void

@see libc/runtime/ftracer.c

ftruncate

Changes size of open file.

If the file size is increased, the extended area shall appear as if it were zero-filled. If your file size is decreased, the extra data shall be lost.

This function never changes the file position. This is true even if ftruncate() causes the position to become beyond the end of file in which case, the rules described in the lseek() documentation apply.

Some operating systems implement an optimization, where length is treated as a logical size and the requested physical space won't be allocated until non-zero values get written into it. Our tests show this happens on Linux (usually with 4096 byte granularity), FreeBSD (which favors 512-byte granularity), and MacOS (prefers 4096 bytes) however Windows, OpenBSD, and NetBSD always reserve physical space. This may be inspected using fstat() and consulting stat::st_blocks.

@param

int fd: must be open for writing
long length: may be greater than current current file size

@return

int: 0 on success, or -1 w/ errno

@raise EINVAL if length is negative

@raise EINTR if signal was delivered instead

@raise ECANCELED if thread was cancelled in masked mode

@raise EIO if a low-level i/o error happened

@raise EFBIG or EINVAL if length is too huge

@raise ENOTSUP if fd is a zip file descriptor

@raise EBADF if fd isn't an open file descriptor

@raise EINVAL if fd is a non-file, e.g. pipe, socket

@raise EINVAL if fd wasn't opened in a writeable mode

@raise ENOSYS on bare metal

@cancellationpoint

@asyncsignalsafe

@threadsafe

@see libc/calls/ftruncate.c

ftrylockfile

Tries to acquire reentrant stdio object lock.

@param

struct FILE* f

@return

int: 0 on success, or non-zero if another thread owns the lock

@see libc/stdio/ftrylockfile.c

ftw

Walks file tree.

@param

const char* path
int(*)() fn
int fd_limit

@return

int

@see examples/walk.c for example

@see nftw()

@see third_party/musl/ftw.c

funlockfile

Releases lock on stdio object.

@param

struct FILE* f

@return

void

@see libc/stdio/funlockfile.c

futimens

Changes access/modified time on open file, the modern way.

XNU only has microsecond (1e-6) accuracy. Windows only has hectonanosecond (1e-7) accuracy. RHEL5 (Linux c. 2007) doesn't support this system call.

@param

int fd: is file descriptor of file whose timestamps will change
ANONYMOUS-STRUCT* ts: is {access, modified} timestamps, or null for current time

@return

int: 0 on success, or -1 w/ errno

@raise ENOTSUP if fd is on the zip filesystem

@raise EINVAL if flags had an unrecognized value

@raise EPERM if pledge() is in play without fattr promise

@raise EINVAL if ts specifies a nanosecond value that's out of range

@raise EBADF if fd isn't an open file descriptor

@raise EFAULT if ts memory was invalid

@raise ENOSYS on RHEL5 or bare metal

@asyncsignalsafe

@threadsafe

@see libc/calls/futimens.c

futimes

Sets atime/mtime on file descriptor.

@param

int fd
struct it_value* tv

@return

int: 0 on success, or -1 w/ errno

@raise ENOTSUP if fd is on zip filesystem

@raise EBADF if fd isn't an open file descriptor

@raise EPERM if pledge() is in play without fattr promise

@raise EINVAL if tv specifies a microsecond value that's out of range

@raise ENOSYS on RHEL5 or bare metal

@see futimens() for modern version

@asyncsignalsafe

@threadsafe

@see libc/calls/futimes.c

futimesat

Changes last accessed/modified times on file.

@param

int dirfd
const char* pathname
ANONYMOUS-STRUCT* tv

@return

int: 0 on success or -1 w/ errno

@see utimensat() which uses nanos

@see libc/time/futimesat.c

__fwritable

Returns nonzero if stream allows reading.

@param

struct FILE* f

@return

int

@see libc/stdio/fwritable.c

fwrite

Writes data to stream.

@param

void* data
unsigned long stride: specifies the size of individual items
unsigned long count: is the number of strides to write
struct FILE* f

@return

unsigned long: count on success, [0,count) on EOF, 0 on error or count==0

@threadsafe

@see libc/stdio/fwrite.c

fwrite_unlocked

Writes data to stream.

@param

void* data
unsigned long stride: specifies the size of individual items
unsigned long count: is the number of strides to write
struct FILE* f

@return

unsigned long: count on success, [0,count) on EOF, 0 on error or count==0

@see libc/stdio/fwrite_unlocked.c

__fwriting

Returns nonzero if stream is write only.

@param

struct FILE* f

@return

int

@see libc/stdio/fwriting.c

g_ddfmt

@param

char* buf
double* dd0
int ndig
unsigned long bufsize

@return

char*

@see third_party/gdtoa/g_ddfmt.c

g_ddfmt_p

@param

char* buf
double* dd0
int ndig
unsigned long bufsize
int nik

@return

char*

@see third_party/gdtoa/g_ddfmt_p.c

g_dfmt

@param

char* buf
double* d
int ndig
unsigned long bufsize

@return

char*

@see third_party/gdtoa/g_dfmt.c

g_dfmt_p

@param

char* buf
double* d
int ndig
unsigned long bufsize
int nik

@return

char*

@see third_party/gdtoa/g_dfmt_p.c

g_fds

@type

struct g_fds

@see libc/intrin/g_fds.c

g_ffmt

@param

char* buf
float* f
int ndig
unsigned long bufsize

@return

char*

@see third_party/gdtoa/g_ffmt.c

g_ffmt_p

@param

char* buf
float* f
int ndig
unsigned long bufsize
int nik

@return

char*

@see third_party/gdtoa/g_ffmt_p.c

g_isrunningundermake

@type

_Bool

@see libc/intrin/isrunningundermake.c

g_isrunningundermake_init

@return

void

@see libc/intrin/isrunningundermake.c

g_xfmt

@param

char* buf
void* V
int ndig
unsigned long bufsize

@return

char*

@see third_party/gdtoa/g_xfmt.c

g_xfmt_p

@param

char* buf
void* V
int ndig
unsigned long bufsize
int nik

@return

char*

@see third_party/gdtoa/g_xfmt_p.c

gai_strerror

Turns getaddrinfo() return code into string.

@param

int code

@return

const char*

@see libc/dns/gai_strerror.c

_gc

Frees memory when function returns.

const char *s = _gc(strdup("hello"));
puts(s);

This macro is equivalent to:

 _defer(free, ptr)

@param

void* thing

@return

void*

@warning do not return a gc()'d pointer

@warning do not realloc() with gc()'d pointer

@warning be careful about static keyword due to impact of inlining

@note you should use -fno-omit-frame-pointer

@threadsafe

@see libc/mem/gc.c

__gc

Invokes deferred function calls.

This offers behavior similar to std::unique_ptr. Functions overwrite their return addresses jumping here, and pushing exactly one entry on the shadow stack below. Functions may repeat that process multiple times, in which case the body of this gadget loops and unwinds as a natural consequence.

@param

rax,rdx,xmm0,xmm1,st0,st1: is return value

@return

@see test/libc/runtime/gc_test.c

@threadsafe

@see libc/nexgen32e/gc.S

_gclongjmp

Jumps up stack to previous setjmp() invocation.

This is the same as longjmp() but also unwinds the stack to free memory, etc. that was registered using gc() or defer(). If GC isn't linked, this behaves the same as longjmp().

@param

rdi: points to the jmp_buf which must be the same stack
esi: is returned by setjmp() invocation (coerced nonzero)

@noreturn

@assume system five nexgen32e abi conformant

@see examples/ctrlc.c

@threadsafe

@see libc/nexgen32e/gclongjmp.S

gcvt

@param

double value
int ndigit
char* buf

@return

char*

@see libc/stdio/gcvt.c

gdbexec

Attaches GDB temporarily, to do something like print a variable.

@param

const char* cmd

@return

int

@see libc/log/gdbexec.c

gdtoa

@param

struct FPI* fpi
int be
unsigned int* bits
int* kindp
int mode
int ndigits
int* decpt
char** rve

@return

char*

@see third_party/gdtoa/gdtoa.c

GenerateConsoleCtrlEvent

Sends signal to process group that shares console w/ calling process.

@param

unsigned int dwCtrlEvent: can be kNtCtrlCEvent or kNtCtrlBreakEvent
unsigned int dwProcessGroupId

@return

int

@note this wrapper takes care of ABI, STRACE(), and __winerr()

@see libc/intrin/generateconsolectrlevent.c

get_current_dir_name

Returns current working directory.

If the PWD environment variable is set, and it seems legit, then that'll be returned.

@return

char*: pointer that must be free()'d, or NULL w/ errno

@threadsafe

@see libc/mem/get_current_dir_name.c

__get_symbol

Returns low index into symbol table for address.

@param

struct SymbolTable* t: if null will be auto-populated only if already open
long a

@return

int: index or -1 if nothing found

@see libc/runtime/getsymboltable.c

__get_virtual

Returns pointer to page table entry for page at virtual address. Additional page tables are allocated if needed as a side-effect.

@param

struct mman* mm
unsigned long* t
long vaddr
_Bool maketables

@return

unsigned long*

@see libc/intrin/mman.greg.c

GetAddr2linePath

@return

const char*

@see libc/log/addr2linepath.c

getaddrinfo

Resolves address for internet name.

@param

const char* name: is either an ip string or a utf-8 hostname
const char* service: is the port number as a string
struct addrinfo* hints: may be passed to specialize behavior (optional)
struct addrinfo** res: receives a pointer that must be freed with freeaddrinfo(), and won't be modified if non-zero is returned

@return

int: 0 on success or EAI_xxx value

@threadsafe

@see libc/dns/getaddrinfo.c

getauxval

Returns auxiliary value, or zero if kernel didn't provide it.

This function is typically regarded as a libc implementation detail; thus, the source code is the documentation.

@param

unsigned long at

@return

unsigned long: auxiliary value or 0 if at not found

@see libc/sysv/consts.sh

@see System Five Application Binary Interface § 3.4.3

@error ENOENT when value not found

@asyncsignalsafe

@see libc/calls/getauxval.c

_getauxval

Returns auxiliary value, or zero if kernel didn't provide it.

This function is typically regarded as a libc implementation detail; thus, the source code is the documentation.

@param

unsigned long at: is AT_... search key

@return

struct AuxiliaryValue: true if value was found

@see libc/sysv/consts.sh

@see System Five Application Binary Interface § 3.4.3

@error ENOENT when value not found

@asyncsignalsafe

@see libc/intrin/_getauxval.c

getc

Reads byte from stream.

@param

struct FILE* f

@return

int: byte in range 0..255, or -1 w/ errno

@threadsafe

@see libc/stdio/getc.c

getc_unlocked

Reads byte from stream.

@param

struct FILE* f

@return

int: byte in range 0..255, or -1 w/ errno

@see libc/stdio/getc_unlocked.c

_getcachesize

Returns CPU cache size.

@param

int type: 1=data, 2=instruction, 3=unified
int level: starts at 1

@return

unsigned int: size in bytes, or 0 if unknown

@see libc/str/getcachesize.c

GetCallerName

Returns name of function that called caller function.

@param

struct StackFrame* bp

@return

const char*

@see libc/log/getcallername.c

getchar

Reads byte from stdin.

@return

int: byte in range 0..255, or -1 w/ errno

@htreadsafe

@see libc/stdio/getchar.c

getchar_unlocked

Reads byte from stdin.

@return

int: byte in range 0..255, or -1 w/ errno

@see libc/stdio/getchar_unlocked.c

getcontext

Gets machine state.

@return

@see setcontext()

@see libc/calls/getcontext.S

_getcpucount

Returns number of CPUs in system.

This is the same as the standard interface:

sysconf(_SC_NPROCESSORS_ONLN);

Except this function isn't a bloated diamond dependency.

On Intel systems with HyperThreading this will return the number of cores multiplied by two.

@return

unsigned int: cpu count or 0 if it couldn't be determined

@see libc/calls/getcpucount.c

GetCpuidBrand

@param

char* s
unsigned int leaf

@return

void

@see libc/intrin/getcpuidbrand.c

GetCpuidEmulator

@return

const char*

@see libc/intrin/getcpuidemulator.c

GetCpuidOs

@return

const char*

@see libc/intrin/getcpuidos.c

getcwd

Returns current working directory, e.g.

const char *dirname = gc(getcwd(0,0)); // if malloc is linked
const char *dirname = getcwd(alloca(PATH_MAX),PATH_MAX);

@param

char* buf: is where UTF-8 NUL-terminated path string gets written, which may be NULL to ask this function to malloc a buffer
unsigned long size: is number of bytes available in buf, e.g. PATH_MAX+1, which may be 0 if buf is NULL

@return

char*: buf containing system-normative path or NULL w/ errno

@error ERANGE, EINVAL, ENOMEM

@see libc/calls/getcwd.greg.c

getdelim

Reads string from stream, e.g.

char *line = NULL;
size_t linesize = 0;
while (getdelim(&line, &linesize, '\n', stdin) > 0) {
  _chomp(line);
  printf("%s\n", line);
}
free(line);

@param

char** s: is the caller's buffer (in/out) which is extended or allocated automatically, also NUL-terminated is guaranteed
unsigned long* n: is the capacity of s (in/out)
int delim: is the stop char (and NUL is implicitly too)
struct FILE* f

@return

long: number of bytes read >0, including delim, excluding NUL, or -1 w/ errno on EOF or error; see ferror() and feof()

@note this function will ignore EINTR if it occurs mid-line

@raises EBADF if stream isn't open for reading

@see fgetln(), getline(), _chomp(), gettok_r()

@see libc/stdio/getdelim.c

getdelim_unlocked

Reads string from unlocked stream.

@param

char** s
unsigned long* n
int delim
struct FILE* f

@return

long

@see getdelim() for documentation

@see libc/stdio/getdelim_unlocked.c

getdomainname

Returns domain of current host.

For example, if the fully-qualified hostname is "host.domain.example" then this SHOULD return "domain.example" however, it might not be the case; it depends on how the host machine is configured.

The nul / mutation semantics are tricky. Here is some safe copypasta:

char domain[254];
if (getdomainname(domain, sizeof(domain))) {
  strcpy(domain, "(none)");
}

On Linux this is the same as /proc/sys/kernel/domainname. However, we turn the weird "(none)" string into empty string.

@param

char* name: receives output name, which is guaranteed to be complete and have a nul-terminator if this function return zero
unsigned long len: is size of name consider using DNS_NAME_MAX + 1 (254)

@return

int: 0 on success, or -1 w/ errno

@raise EINVAL if len is negative

@raise EFAULT if name is an invalid address

@raise ENAMETOOLONG if the underlying system call succeeded, but the returned hostname had a length equal to or greater than len in which case this error is raised and the buffer is modified, with as many bytes of hostname as possible excluding a nul-terminator

@see libc/calls/getdomainname.c

getdomainname_linux

@param

char* name
unsigned long len

@return

int

@see libc/calls/getdomainname-linux.c

GetDosArgv

@param

const unsigned short* cmdline
char* buf
unsigned long size
char** argv
unsigned long max

@return

int

@see libc/runtime/getdosargv.c

GetDosEnviron

@param

const unsigned short* env
char* buf
unsigned long size
char** envp
unsigned long max

@return

int

@see libc/runtime/getdosenviron.c

getdtablesize

Gets file descriptor table size.

@return

int: current limit on the number of open files per process

@see libc/calls/getdtablesize.c

getegid

Returns effective group ID of calling process.

@return

unsigned int: group id

@see libc/calls/getegid.c

GetElfDynStringTable

@param

struct Elf64_Ehdr* elf
unsigned long mapsize

@return

char*

@see libc/elf/getelfdynstringtable.c

GetElfDynSymbolTable

@param

struct Elf64_Ehdr* elf
unsigned long mapsize
unsigned long* out_count

@return

struct Elf64_Sym*

@see libc/elf/getelfdynsymboltable.c

GetElfSectionAddress

@param

struct Elf64_Ehdr* elf
unsigned long mapsize
struct Elf64_Shdr* shdr

@return

void*

@see libc/elf/getelfsectionaddress.c

GetElfSectionHeaderAddress

@param

struct Elf64_Ehdr* elf
unsigned long mapsize
unsigned short i

@return

struct Elf64_Shdr*

@see libc/elf/getelfsectionheaderaddress.c

GetElfSectionName

@param

struct Elf64_Ehdr* elf
unsigned long mapsize
struct Elf64_Shdr* shdr

@return

const char*

@see libc/elf/getelfsectionname.c

GetElfSectionNameStringTable

@param

struct Elf64_Ehdr* elf
unsigned long mapsize

@return

char*

@see libc/elf/getelfsectionnamestringtable.c

GetElfSegmentHeaderAddress

@param

struct Elf64_Ehdr* elf
unsigned long mapsize
unsigned int i

@return

struct Elf64_Phdr*

@see libc/elf/getelfsegmentheaderaddress.c

GetElfString

@param

struct Elf64_Ehdr* elf
unsigned long mapsize
const char* strtab
unsigned int rva

@return

char*

@see libc/elf/getelfstring.c

GetElfStringTable

@param

struct Elf64_Ehdr* elf
unsigned long mapsize

@return

char*

@see libc/elf/getelfstringtable.c

GetElfStrs

@param

struct Elf64_Ehdr* elf
unsigned long mapsize
unsigned long* out_size

@return

char*

@see libc/elf/getelfstrs.c

GetElfSymbolTable

@param

struct Elf64_Ehdr* elf
unsigned long mapsize
unsigned long* out_count

@return

struct Elf64_Sym*

@see libc/elf/getelfsymboltable.c

GetElfVirtualAddressRange

@param

struct Elf64_Ehdr* elf
unsigned long elfsize
long* out_start
long* out_end

@return

void

@see libc/elf/getelfvirtualaddressrange.c

getentropy

Returns random seeding bytes, the XNU/OpenBSD way.

@param

void* p
unsigned long n

@return

int: 0 on success, or -1 w/ errno

@raise EFAULT if the n bytes at p aren't valid memory

@raise EIO is returned if more than 256 bytes are requested

@see getrandom()

@see libc/stdio/getentropy.c

getenv

Returns value of environment variable, or NULL if not found.

Environment variables can store empty string on Unix but not Windows.

@param

const char* s

@return

char*: pointer to value of environ entry, or null if not found

@see libc/intrin/getenv.c

geteuid

Returns effective user ID of calling process.

@return

unsigned int: user id

@see libc/calls/geteuid.c

GetExitCodeProcess

Obtains exit code for process.

@param

long hProcess
unsigned int* lpExitCode

@return

int

@note this wrapper takes care of ABI, STRACE(), and __winerr()

@see libc/intrin/getexitcodeprocess.c

GetFileAttributes

Gets file info on the New Technology.

@param

const unsigned short* lpPathName

@return

unsigned int: handle, or -1u on failure

@note this wrapper takes care of ABI, STRACE(), and __winerr()

@see libc/intrin/getfileattributes.c

getfiledescriptorsize

Determines size of open file.

This function is equivalent to:

struct stat st;
!fstat(fd, &st) ? st.st_size : -1

Except faster on BSD/Windows and a much smaller link size.

@param

int fd

@return

long: file byte length, or -1 w/ errno

@asyncsignalsafe

@see libc/calls/getfiledescriptorsize.c

GetGdbPath

@return

const char*

@see libc/log/gdbpath.c

getgid

Returns real group id of process.

This never fails. On Windows, which doesn't really have this concept, we return a deterministic value that's likely to work.

@return

unsigned int: group id (always successful)

@asyncsignalsafe

@threadsafe

@vforksafe

@see libc/calls/getuid.c

getgrent

@return

struct gr*

@see third_party/musl/grp.c

getgrgid

@param

unsigned int gid

@return

struct gr*

@see third_party/musl/grp.c

getgrgid_r

@param

unsigned int gid
struct gr* gr
char* buf
unsigned long size
struct gr** res

@return

int

@see third_party/musl/grp.c

getgrnam

@param

const char* name

@return

struct gr*

@see third_party/musl/grp.c

getgrnam_r

@param

const char* name
struct gr* gr
char* buf
unsigned long size
struct gr** res

@return

int

@see third_party/musl/grp.c

getgrouplist

@param

const char* user
unsigned int gid
unsigned int* groups
int* ngroups

@return

int

@see third_party/musl/grp.c

getgroups

Gets list of supplementary group IDs

@param

int size

maximum number of items that can be stored in list

unsigned int* list

buffer to store output gid_t

@return

int: -1 w/ EFAULT

@see libc/calls/getgroups.c

gethostbyaddr

@param

void* s_addr
unsigned int len
int type

@return

struct he1*

@see libc/dns/gethostbyaddr.c

gethostbyname

@param

const char* name

@return

struct he0*

@see libc/dns/gethostbyname.c

gethostent

@return

struct hostent*

@see libc/dns/hostent.c

GetHostIps

Returns IP addresses of system.

Normally return values will look like {0x7f000001, 0x0a0a0a7c, 0} which means the same thing as {"127.0.0.1", "10.10.10.124", 0}. Returned IPs will IPv4 anycast addresses bound to network interfaces which come in a NULL-terminated array with no particular ordering.

uint32_t *ip, *ips = GetIps();
for (ip = ips; *ip; ++ip) {
  printf("%hhu.%hhu.%hhu.%hhu\n", *ip >> 24, *ip >> 16, *ip >> 8, *ip);
}

This function supports Windows, Linux, XNU, FreeBSD, NetBSD, OpenBSD.

@return

unsigned int*: null-terminated ip array on success, or null w/ errno

@see libc/sock/gethostips.c

gethostname

Returns name of current host.

For example, if the fully-qualified hostname is "host.domain.example" then this SHOULD return "host" however that might not be the case; it depends on how the host machine is configured. It's fair to say if it has a dot, it's a FQDN, otherwise it's a node.

The nul / mutation semantics are tricky. Here is some safe copypasta:

char host[254];
if (gethostname(host, sizeof(host))) {
  strcpy(host, "localhost");
}

On Linux this is the same as /proc/sys/kernel/hostname.

@param

char* name: receives output name, which is guaranteed to be complete and have a nul-terminator if this function return zero
unsigned long len: is size of name consider using DNS_NAME_MAX + 1 (254)

@return

int: 0 on success, or -1 w/ errno

@raise EINVAL if len is negative

@raise EFAULT if name is an invalid address

@see libc/calls/gethostname.c

gethostname_bsd

@param

char* name
unsigned long len
int kind

@return

int

@see libc/calls/gethostname-bsd.c

gethostname_linux

@param

char* name
unsigned long len

@return

int

@see libc/calls/gethostname-linux.c

gethostname_nt

@param

char* name
unsigned long len
int kind

@return

int

@see libc/calls/gethostname-nt.c

GetHostsTxt

Returns hosts.txt map.

@return

struct HostsTxt*

@note yoinking realloc() ensures there's no size limits

@threadsafe

@see libc/dns/gethoststxt.c

GetHttpHeader

Returns small number for HTTP header, or -1 if not found.

@param

const char* str
unsigned long len

@return

int

@see net/http/gethttpheader.c

GetHttpHeaderName

@param

int h

@return

const char*

@see net/http/gethttpheadername.c

GetHttpMethod

Converts HTTP method string into internal index

@param

const char* str
unsigned long len: if -1 implies strlen

@return

int: small number for HTTP method, or 0 if not found.

@see net/http/gethttpmethod.c

GetHttpReason

Returns string describing HTTP reason phrase.

@param

int code

@return

const char*

@see https://tools.ietf.org/html/rfc2616

@see https://tools.ietf.org/html/rfc6585

@see net/http/gethttpreason.c

GetInterpreterExecutableName

Returns path of executable interpreter.

Unlike program_executable_name which is designed to figure out the absolute path of the first argument passed to execve(), what we do here is probe things like /proc and sysctl() to figure out if we were launched by something like ape-loader, and then we return its path. If we can't determine that path, possibly because we're on XNU or OpenBSD, then we return -1 with an error code.

@param

char* p: receives utf8 output
unsigned long n: is byte size of res buffer

@return

char*: p on success or null w/ errno if out of buf or error

@see program_invocation_short_name

@see program_invocation_name

@see program_executable_name

@see libc/runtime/getinterpreterexecutablename.c

GetIpCategoryName

Describes IP address.

@param

int c

@return

const char*

@see CategorizeIp()

@see net/http/getipcategoryname.c

getitimer

Retrieves last setitimer() value, correcting for remaining time.

@param

int which: can be ITIMER_REAL, ITIMER_VIRTUAL, etc.
struct itimerval* curvalue

@return

int: 0 on success or -1 w/ errno

@see libc/calls/getitimer.c

getline

Reads line from stream, e.g.

char *line = NULL;
size_t linesize = 0;
while (getline(&line, &linesize, stdin) > 0) {
  _chomp(line);
  printf("%s\n", line);
}
free(line);

This function delegates to getdelim(), which provides further documentation. Concerning lines, please note the \n or \r\n are included in results, and can be removed with _chomp().

@param

char** line: is the caller's buffer (in/out) which is extended automatically. *line may be NULL but only if *n is 0; NUL-termination is guaranteed FTMP
unsigned long* n
struct FILE* f

@return

long: number of bytes read, including delim, excluding NUL, or -1 w/ errno on EOF or error; see ferror() and feof()

@see fgetln(), xgetline(), getdelim(), gettok_r()

@see libc/stdio/getline.c

getloadavg

Returns system load average.

@param

double* a: should be array of 3 doubles
int n: should be 3

@return

int: number of items placed in a or -1 w/ errno

@raise ENOSYS on metal

@see libc/calls/getloadavg.c

getlogin

Returns login name.

@return

char*

@see libc/runtime/getlogin.c

getlogin_r

Returns login name.

@param

char* buf
unsigned long size

@return

int

@see libc/runtime/getlogin_r.c

GetMagnumStr

@param

struct MagnumStr* ms
int x

@return

char*

@see libc/intrin/getmagnumstr.c

GetMaxFd

Returns maximum number of open files.

@return

long

@see libc/runtime/getmaxfd.c

GetMemtrackSize

@param

struct _mmi* mm

@return

unsigned long

@see libc/runtime/getmemtracksize.c

getmntent

@param

struct FILE* f

@return

struct mnt*

@see third_party/musl/mntent.c

getmntent_r

@param

struct FILE* f
struct mnt* mnt
char* linebuf
int buflen

@return

struct mnt*

@see third_party/musl/mntent.c

getnameinfo

Resolves name/service for socket address.

@param

struct sockaddr* addr
unsigned int addrlen
char* name
unsigned int namelen
char* service
unsigned int servicelen
int flags

@return

int: 0 on success or EAI_xxx value

@see libc/dns/getnameinfo.c

getnetbyaddr

@param

unsigned int net
int type

@return

struct netent*

@see libc/dns/netent.c

getnetbyname

@param

const char* name

@return

struct netent*

@see libc/dns/netent.c

getnetent

@return

struct netent*

@see libc/dns/netent.c

GetNtBaseSocket

@param

long socket

@return

long

@see libc/sock/basesocket.c

GetNtNameServers

Extracts DNS nameserver IPs from Windows Registry.

@param

struct ResolvConf* resolv: points to a ResolvConf object, which should be zero initialized by the caller; or if it already contains items, this function will append

@return

int: number of nameservers appended, or -1 w/ errno

@see libc/dns/getntnameservers.c

GetNtOpenFlags

@param

int flags
int mode
unsigned int* out_perm
unsigned int* out_share
unsigned int* out_disp
unsigned int* out_attr

@return

int

@see libc/calls/createfileflags.c

GetNtProtocolsTxtPath

@param

char* pathbuf
unsigned int size

@return

char*

@see libc/dns/getntprotocolstxtpath.c

GetNtServicesTxtPath

@param

char* pathbuf
unsigned int size

@return

char*

@see libc/dns/getntservicestxtpath.c

__getntsyspath

Obtains WIN32 magic path, e.g. GetTempPathA.

@param

rax: is address of ANSI path provider function
rdi: is output buffer
rdx: is output buffer size in bytes that's >0

@return

: eax is string length w/ NUL that's ≤ edx; rdi is rdi+edx

@see libc/calls/getntsyspath.S

getopt

Parses argc/argv argument vector, e.g.

while ((opt = getopt(argc, argv, "hvx:")) != -1) {
  switch (opt) {
    case 'x':
      x = atoi(optarg);
      break;
    case 'v':
      ++verbose;
      break;
    case 'h':
      PrintUsage(EXIT_SUCCESS, stdout);
    default:
      PrintUsage(EX_USAGE, stderr);
  }
}

@param

int nargc
char** nargv
const char* ostr

@return

int

@see optind

@see optarg

@see third_party/getopt/getopt.c

getpagesize

Returns granularity of memory manager.

@return

@see sysconf(_SC_PAGE_SIZE) which is portable

@see libc/runtime/getpagesize.S

getpeername

Returns details about remote end of connected socket.

@param

int fd
struct sa* out_addr
unsigned int* out_addrsize

@return

int: 0 on success or -1 w/ errno

@see getsockname()

@see libc/sock/getpeername.c

getpgid

Returns process group id.

@param

int pid

@return

int

@see libc/calls/getpgid.c

getpgrp

Returns process group id of calling process.

This function is equivalent to getpgid(0).

@return

int

@see libc/calls/getpgrp.c

getpid

Returns process id.

This function does not need to issue a system call. The PID is tracked by a global variable which is updated at fork(). The only exception is when the process is vfork()'d in which case a system call shall be issued. This optimization helps make functions like _rand64() fork-safe, however it could lead to race conditions in programs that mix fork() with threads. In that case, apps should consider using sys_getpid().ax instead to force a system call.

On Linux, and only Linux, getpid() is guaranteed to equal gettid() for the main thread.

@return

int: process id (always successful)

@asyncsignalsafe

@threadsafe

@vforksafe

@see libc/intrin/getpid.c

getppid

Returns parent process id.

@return

int: parent process id (always successful)

@note slow on Windows; needs to iterate process tree

@asyncsignalsafe

@threadsafe

@vforksafe

@see libc/calls/getppid.c

getpriority

Returns nice value of thing.

Since -1 might be a valid return value for this API, it's necessary to clear errno beforehand and see if it changed, in order to truly determine if an error happened.

On Windows, there's only six priority classes. We define them as -16 (realtime), -10 (high), -5 (above), 0 (normal), 5 (below), 15 (idle) which are the only values that'll roundtrip getpriority/setpriority.

@param

int which

can be one of:

PRIO_PROCESS is supported universally
PRIO_PGRP is supported on unix
PRIO_USER is supported on unix

unsigned int who

is the pid, pgid, or uid (0 means current)

@return

int: value ∈ [-NZERO,NZERO) or -1 w/ errno

@raise EINVAL if which was invalid or unsupported

@raise EPERM if access to process was denied

@raise ESRCH if no such process existed

@see setpriority()

@see libc/calls/getpriority.c

GetProcAddressModule

Returns address of function in a DLL that's already loaded.

@param

const char* module
const char* symbol

@return

void*

@see libc/calls/getprocaddressmodule.c

GetProgramExecutableName

Returns absolute path of program.

@return

char*

@see libc/calls/getprogramexecutablename.greg.c

getprotobyname

@param

const char* name

@return

struct pe0*

@see libc/dns/getprotobyname.c

getprotobynumber

@param

int proto

@return

struct pe1*

@see libc/dns/getprotobynumber.c

getprotoent

@return

struct protoent*

@see libc/dns/protoent.c

getpwent

@return

struct pw*

@see third_party/musl/pwd.c

getpwnam

@param

const char* name

@return

struct pw*

@see third_party/musl/pwd.c

getpwnam_r

@param

const char* name
struct pw* pw
char* buf
unsigned long size
struct pw** res

@return

int

@see third_party/musl/pwd.c

getpwuid

@param

unsigned int uid

@return

struct pw*

@see third_party/musl/pwd.c

getpwuid_r

@param

unsigned int uid
struct pw* pw
char* buf
unsigned long size
struct pw** res

@return

int

@see third_party/musl/pwd.c

getrandom

Returns cryptographic random data.

This random number seed generator obtains information from:

RtlGenRandom() on Windows
getentropy() on XNU and OpenBSD
getrandom() on Linux, FreeBSD, and NetBSD
sysctl(KERN_ARND) on older versions of FreeBSD and NetBSD

Unlike getentropy() this function is interruptible. However EINTR shouldn't be possible if f is zero and n is no more than 256, noting that kernels are a bit vague with their promises here, and if you're willing to trade some performance for a more assurances that EINTR won't happen, then either consider using getentropy(), or using the SA_RESTART flag on your signal handlers.

Unlike getentropy() you may specify an n greater than 256. When larger amounts are specified, the caller must be prepared for the case where fewer than n bytes are returned. In that case, it is likely that a signal delivery occured. Cancellations in mask mode also need to be suppressed while processing the bytes beyond 256. On BSD OSes, this entire process is uninterruptible so be careful when using large sizes if interruptibility is needed.

Unlike getentropy() this function is a cancellation point. But it shouldn't be a problem, unless you're using masked mode, in which case extra care must be taken to consider the result.

It's recommended that f be set to zero, although it may include the following flags:

GRND_NONBLOCK when you want to elevate the insecurity of your random data
GRND_RANDOM if you want to have the best possible chance your program will freeze and the system operator is paged to address the outage by driving to the data center and jiggling the mouse

@param

void* p
unsigned long n
unsigned int f

@return

long

@note this function could block a nontrivial time on old computers

@note this function is indeed intended for cryptography

@note this function takes around 900 cycles

@raise EINVAL if f is invalid

@raise ECANCELED if thread was cancelled in masked mode

@raise EFAULT if the n bytes at p aren't valid memory

@raise EINTR if we needed to block and a signal was delivered instead

@cancellationpoint

@asyncsignalsafe

@restartable

@vforksafe

@see libc/stdio/getrandom.c

getresgid

Gets real, effective, and "saved" group ids.

@param

unsigned int* real: receives real user id, or null to do nothing
unsigned int* effective: receives effective user id, or null to do nothing
unsigned int* saved: receives saved user id, or null to do nothing

@return

int: 0 on success or -1 w/ errno

@see setresuid()

@see libc/calls/getresgid.c

GetResolvConf

Returns singleton with DNS server address.

@return

struct ResolvConf*

@threadsafe

@see libc/dns/getresolvconf.c

GetResourceLimit

@param

int resource

@return

long

@see libc/runtime/getresourcelimit.c

getresuid

Gets real, effective, and "saved" user ids.

@param

unsigned int* real: receives real user id, or null to do nothing
unsigned int* effective: receives effective user id, or null to do nothing
unsigned int* saved: receives saved user id, or null to do nothing

@return

int: 0 on success or -1 w/ errno

@see setresuid()

@see libc/calls/getresuid.c

getrlimit

Gets resource limit for current process.

@param

int resource: can be RLIMIT_{CPU,FSIZE,DATA,STACK,CORE,RSS,etc.}
struct rlimit* rlim: receives result, modified only on success

@return

int: 0 on success or -1 w/ errno

@see libc/sysv/consts.sh

@see libc/calls/getrlimit.c

getrusage

Returns resource usage statistics.

@param

int who: can be RUSAGE_{SELF,CHILDREN,THREAD}
struct rusage* usage

@return

int: 0 on success, or -1 w/ errno

@see libc/calls/getrusage.c

gets

@param

char* s

@return

char*

@see libc/stdio/gets.c

getservbyname

@param

const char* name
const char* proto

@return

struct se0*

@see libc/dns/getservbyname.c

getservbyport

@param

int port
const char* proto

@return

struct se1*

@see libc/dns/getservbyport.c

getservent

@return

struct servent*

@see libc/dns/servent.c

GetSiCodeName

Returns symbolic name for siginfo::si_code value.

@param

int sig
int si_code

@return

const char*

@see libc/log/getsicodename.c

getsid

Creates session and sets the process group id.

@param

int pid

@return

int

@see libc/calls/getsid.c

getsockname

Returns details about network interface kernel granted socket.

@param

int fd
struct sa* out_addr
unsigned int* out_addrsize

@return

int: 0 on success or -1 w/ errno

@see getpeername()

@see libc/sock/getsockname.c

getsockopt

Retrieves socket setting.

@param

int fd
int level: can be SOL_SOCKET, IPPROTO_TCP, etc.
int optname: can be SO_{REUSE{PORT,ADDR},KEEPALIVE,etc.} etc.
void* out_opt_optval
unsigned int* out_optlen

@return

int: 0 on success, or -1 w/ errno

@error ENOPROTOOPT for unknown (level,optname)

@error EINVAL if out_optlen is invalid somehow

@error ENOTSOCK if fd is valid but not a socket

@error EBADF if fd isn't valid

@error EFAULT if optval memory isn't valid

@see libc/sysv/consts.sh for tuning catalogue

@see setsockopt()

@see libc/sock/getsockopt.c

getsubopt

@param

char** optionp
char** tokens
char** valuep

@return

int

@see third_party/getopt/getsubopt.c

GetSymbolByAddr

Returns name of symbol at address.

@param

long addr

@return

char*

@see libc/log/getsymbolbyaddr.c

GetSymbolTable

Returns symbol table singleton.

This uses multiple strategies to find the symbol table. The first strategy, depends on whether or not the following is linked:

STATIC_YOINK("__zipos_get");

In that case, the symbol table may be read from /zip/.symtab which is generated by o//tool/build/symtab.com. The second strategy is to look for the concomitant .com.dbg executable, which may very well be the one currently executing, or it could be placed in the same folder as your .com binary, or lastly, it could be explicitly specified via the COMDBG environment variable.

Function tracing is disabled throughout the duration of this call. Backtraces and other core runtime functionality depend on this.

@return

struct SymbolTable*: symbol table, or NULL if not found

@see libc/runtime/getsymboltable.c

GetTempPathA_flunk

Calls GetTempPathA() w/ different API.

@return

@see GetSystemDirectoryA(), GetWindowsDirectoryA()

@see libc/calls/gettemppatha-flunk.S

gettid

Returns current thread id.

On Linux, and Linux only, this is guaranteed to be equal to getpid() if this is the main thread. On NetBSD, gettid() for the main thread is always 1.

@return

int: thread id greater than zero or -1 w/ errno

@asyncsignalsafe

@threadsafe

@vforksafe

@see libc/intrin/gettid.c

gettimeofday

Returns system wall time in microseconds, e.g.

int64_t t;
char p[30];
struct tm tm;
struct timeval tv;
gettimeofday(&tv, 0);
t = tv.tv_sec;
gmtime_r(&t, &tm);
FormatHttpDateTime(p, &tm);
printf("%s\n", p);

@param

struct it_value* tv: points to timeval that receives result if non-NULL
struct timezone* tz: receives UTC timezone if non-NULL

@return

int

@error EFAULT if tv or tz isn't valid memory

@see clock_gettime() for nanosecond precision

@see strftime() for string formatting

@see libc/calls/gettimeofday.c

__gettimeofday_get

Returns pointer to fastest gettimeofday().

@param

_Bool* opt_out_isfast

@return

struct ad(*)()

@see libc/calls/gettimeofday.c

_getttysize

Returns dimensions of controlling terminal.

It is recommended that programs err on the side of showing more information, if this value can't be obtained with certainty.

@param

int fd
struct winsize* out: stores determined dimensions, only on success

@return

int

@returns -1 on error or something else on success

@see libc/calls/getttysize.c

getuid

Returns real user id of process.

This never fails. On Windows, which doesn't really have this concept, we return a deterministic value that's likely to work.

@return

unsigned int: user id (always successful)

@asyncsignalsafe

@threadsafe

@vforksafe

@see libc/calls/getuid.c

getutline

Searches forward in the user accounting database.

@return

@note unsupported

@see libc/runtime/getutxline.S

getutxent

Reads next entry in user accounting database.

@return

@note unsupported

@see libc/runtime/getutxent.S

getutxid

Searches forward in the user accounting database.

@return

@note unsupported

@see libc/runtime/getutxid.S

getutxline

Searches forward in the user accounting database.

@return

@note unsupported

@see libc/runtime/getutxline.S

getwc

Reads UTF-8 character from stream.

@param

struct FILE* f

@return

unsigned int: wide character or -1 on EOF or error

@threadsafe

@see libc/stdio/getwc.c

getwc_unlocked

Reads UTF-8 character from stream.

@param

struct FILE* f

@return

unsigned int: wide character or -1 on EOF or error

@see libc/stdio/getwc_unlocked.c

getwchar

Reads UTF-8 character from stream.

@return

unsigned int: wide character or -1 on EOF or error

@threadsafe

@see libc/stdio/getwchar.c

getwchar_unlocked

Reads UTF-8 character from stream.

@return

unsigned int: wide character or -1 on EOF or error

@see libc/stdio/getwchar_unlocked.c

getx86processormodel

Identifies microarchitecture of host processor.

@param

short key: can be kX86ProcessorModelKey for host info

@return

struct X86ProcessorModel*

@see https://en.wikichip.org/wiki/intel/cpuid

@see https://a4lg.com/tech/x86/database/x86-families-and-models.en.html

@see libc/str/getx86processormodel.c

GetZipCdirComment

Returns comment of zip central directory.

@param

const unsigned char* eocd

@return

void*

@see libc/str/getzipcdircomment.c

GetZipCdirCommentSize

Returns comment of zip central directory.

@param

const unsigned char* eocd

@return

unsigned long

@see libc/str/getzipcdircommentsize.c

GetZipCdirOffset

Returns offset of zip central directory.

@param

const unsigned char* eocd

@return

unsigned long

@see libc/str/getzipcdiroffset.c

GetZipCdirRecords

Returns number of records in zip central directory.

@param

const unsigned char* eocd

@return

unsigned long

@see libc/str/getzipcdirrecords.c

GetZipCdirSize

Returns size of zip central directory.

@param

const unsigned char* eocd

@return

unsigned long

@see libc/str/getzipcdirsize.c

GetZipCfileCompressedSize

Returns compressed size in bytes from zip central directory header.

@param

const unsigned char* z

@return

unsigned long

@see libc/str/getzipcfilecompressedsize.c

GetZipCfileMode

Returns st_mode from ZIP central directory record.

@param

const unsigned char* p

@return

int

@see libc/str/getzipcfilemode.c

GetZipCfileOffset

Returns offset of local file header.

@param

const unsigned char* z

@return

unsigned long

@see libc/str/getzipcfileoffset.c

GetZipCfileTimestamps

Extracts modified/access/creation timestamps from zip entry.

@param

const unsigned char* cf: is pointer to central directory header for file
ANONYMOUS-STRUCT* mtim: optionally receives last modified timestamp
ANONYMOUS-STRUCT* atim: optionally receives modified timestamp
ANONYMOUS-STRUCT* ctim: optionally receives creation timestamp
int gmtoff: is seconds adjustment for legacy dos timestamps

@return

void

@see libc/str/getzipcfiletimestamps.c

GetZipCfileUncompressedSize

Returns uncompressed size in bytes from zip central directory header.

@param

const unsigned char* z

@return

unsigned long

@see libc/str/getzipcfileuncompressedsize.c

GetZipLfileCompressedSize

Returns compressed size in bytes from zip local file header.

@param

const unsigned char* z

@return

unsigned long

@see libc/str/getziplfilecompressedsize.c

GetZipLfileUncompressedSize

Returns uncompressed size in bytes from zip local file header.

@param

const unsigned char* z

@return

unsigned long

@see libc/str/getziplfileuncompressedsize.c

glob

Finds pathnames matching pattern.

For example:

glob_t g = {.gl_offs = 2};
glob("*.*", GLOB_DOOFFS, NULL, &g);
glob("../.*", GLOB_DOOFFS | GLOB_APPEND, NULL, &g);
g.gl_pathv[0] = "ls";
g.gl_pathv[1] = "-l";
execvp("ls", &g.gl_pathv[0]);
globfree(g);

@param

const char* pat: can have star wildcard see fnmatch()
int flags
int(*)() errfunc
struct glob_t* g: will receive matching entries and needs globfree()

@return

int: 0 on success or GLOB_NOMATCH, GLOB_NOSPACE on OOM, or GLOB_ABORTED on read error

@see third_party/musl/glob.c

globfree

Frees entries allocated by glob().

@param

struct glob_t* g

@return

void

@see third_party/musl/glob.c

gmtime

@param

const long* timep

@return

struct alttm*

@see libc/time/localtime.c

gmtime_r

@param

const long* timep
struct alttm* tmp

@return

struct alttm*

@see libc/time/localtime.c

GoodSocket

Returns new socket with modern goodness enabled.

@param

int family
int type
int protocol
_Bool isserver
ANONYMOUS-STRUCT* timeout

@return

int

@see libc/sock/goodsocket.c

grantpt

Grants access to subordinate pseudoteletypewriter.

@param

int fd

@return

int: 0 on success, or -1 w/ errno

@raise EBADF if fd isn't open

@raise EINVAL if fd is valid but not associated with pty

@raise EACCES if pseudoterminal couldn't be accessed

@see libc/calls/grantpt.c

gray

Returns gray code for x.

@param

unsigned int x

@return

unsigned int

@see https://en.wikipedia.org/wiki/Gray_code

@see ungray()

@see libc/intrin/gray.c

__grow

Grows array.

@param

void* pp
unsigned long* capacity
unsigned long itemsize
unsigned long extra

@return

_Bool

@deprecated favor realloc

@see libc/runtime/grow.c

gzbuffer

Sets internal buffer size used by this library's functions. The default buffer size is 8192 bytes. This function must be called after gzopen() or gzdopen(), and before any other calls that read or write the file. The buffer memory allocation is always deferred to the first read or write. Three times that size in buffer space is allocated. A larger buffer size of, for example, 64K or 128K bytes will noticeably increase the speed of decompression (reading).

The new buffer size also affects the maximum length for gzprintf().

@return

int: Z_OK on success, or -1 on failure, such as being called too late.

@see third_party/zlib/zlib.h

gzclearerr

Clears the error and end-of-file flags for file. This is analogous to the clearerr() function in stdio. This is useful for continuing to read a gzip file that is being written concurrently.

@return

void

@see third_party/zlib/zlib.h

gzclose

Flushes all pending output if necessary, closes the compressed file and deallocates the (de)compression state. Note that once file is closed, you cannot call gzerror with file, since its structures have been deallocated. gzclose must not be called more than once on the same file, just as free must not be called more than once on the same allocation.

@return

int: Z_STREAM_ERROR if file is not valid, Z_ERRNO on a file operation error, Z_MEM_ERROR if out of memory, Z_BUF_ERROR if the last read ended in the middle of a gzip stream, or Z_OK on success.

@see third_party/zlib/zlib.h

gzclose_r

Same as gzclose(), but gzclose_r() is only for use when reading, and gzclose_w() is only for use when writing or appending. The advantage to using these instead of gzclose() is that they avoid linking in zlib compression or decompression code that is not used when only reading or only writing respectively. If gzclose() is used, then both compression and decompression code will be included the application when linking to a static zlib library.

@return

int

@see third_party/zlib/zlib.h

gzdirect

Returns true (1) if file is being copied directly while reading, or false (0) if file is a gzip stream being decompressed.

If the input file is empty, gzdirect() will return true, since the input does not contain a gzip stream.

If gzdirect() is used immediately after gzopen() or gzdopen() it will cause buffers to be allocated to allow reading the file to determine if it is a gzip file. Therefore if gzbuffer() is used, it should be called before gzdirect().

When writing, gzdirect() returns true (1) if transparent writing was requested ("wT" for the gzopen() mode), or false (0) otherwise. (Note: gzdirect() is not needed when writing. Transparent writing must be explicitly requested, so the application already knows the answer. When linking statically, using gzdirect() will include all of the zlib code for gzip file reading and decompression, which may not be desired.)

@return

int

@see third_party/zlib/zlib.h

gzdopen

Associates gzFile with the file descriptor.

File descriptors are obtained from calls like open, dup, creat, pipe or fileno (if the file has been previously opened with fopen). The mode parameter is as in gzopen.

The next call of gzclose on the returned gzFile will also close the file descriptor fd, just like fclose(fdopen(fd, mode)) closes the file descriptor fd. If you want to keep fd open, use fd = dup(fd_keep); gz = gzdopen(fd, mode);. The duplicated descriptor should be saved to avoid a leak, since gzdopen does not close fd if it fails. If you are using fileno() to get the file descriptor from a FILE *, then you will have to use dup() to avoid double-close()ing the file descriptor. Both gzclose() and fclose() will close the associated file descriptor, so they need to have different file descriptors.

@return

struct gzFile_s*: Z_OK if there was insufficient memory to allocate the gzFile state, if an invalid mode was specified (an 'r', 'w', or 'a' was not provided, or '+' was provided), or if fd is -1. The file descriptor is not used until the next gz* read, write, seek, or close operation, so gzdopen will not detect if fd is invalid (unless fd is -1).

@see third_party/zlib/zlib.h

gzeof

Returns true (1) if the end-of-file indicator has been set while reading, false (0) otherwise. Note that the end-of-file indicator is set only if the read tried to go past the end of the input, but came up short. Therefore, just like feof(), gzeof() may return false even if there is no more data to read, in the event that the last read request was for the exact number of bytes remaining in the input file. This will happen if the input file size is an exact multiple of the buffer size.

If gzeof() returns true, then the read functions will return no more data, unless the end-of-file indicator is reset by gzclearerr() and the input file has grown since the previous end of file was detected.

@return

int

@see third_party/zlib/zlib.h

gzerror

Returns the error message for the last error which occurred on the given compressed file. errnum is set to zlib error number. If an error occurred in the file system and not in the compression library, errnum is set to Z_ERRNO and the application may consult errno to get the exact error code.

The application must not modify the returned string. Future calls to this function may invalidate the previously returned string. If file is closed, then the string previously returned by gzerror will no longer be available.

gzerror() should be used to distinguish errors from end-of-file for those functions above that do not distinguish those cases in their return values.

@return

const char*

@see third_party/zlib/zlib.h

gzflush

Flushes all pending output into the compressed file. The parameter flush is as in the deflate() function. The return value is the zlib error number (see function gzerror below). gzflush is only permitted when writing.

If the flush parameter is Z_FINISH, the remaining data is written and the gzip stream is completed in the output. If gzwrite() is called again, a new gzip stream will be started in the output. gzread() is able to read such concatenated gzip streams.

gzflush should be called only when strictly necessary because it will degrade compression if called too often.

@return

int

@see third_party/zlib/zlib.h

gzfread

Read up to nitems items of size size from file to buf, otherwise operating as gzread() does. This duplicates the interface of stdio's fread(), with size_t request and return types. If the library defines size_t, then size_t is identical to size_t. If not, then size_t is an unsigned integer type that can contain a pointer.

gzfread() returns the number of full items read of size size, or zero if the end of the file was reached and a full item could not be read, or if there was an error. gzerror() must be consulted if zero is returned in order to determine if there was an error. If the multiplication of size and nitems overflows, i.e. the product does not fit in a size_t, then nothing is read, zero is returned, and the error state is set to Z_STREAM_ERROR.

In the event that the end of file is reached and only a partial item is available at the end, i.e. the remaining uncompressed data length is not a multiple of size, then the final partial item is nevetheless read into buf and the end-of-file flag is set. The length of the partial item read is not provided, but could be inferred from the result of gztell(). This behavior is the same as the behavior of fread() implementations in common libraries, but it prevents the direct use of gzfread() to read a concurrently written file, reseting and retrying on end-of-file, when size is not 1.

@return

unsigned long

@see third_party/zlib/zlib.h

gzfwrite

Writes nitems items of size size from buf to file, duplicating the interface of stdio's fwrite(), with size_t request and return types. If the library defines size_t, then size_t is identical to size_t. If not, then size_t is an unsigned integer type that can contain a pointer.

gzfwrite() returns the number of full items written of size size, or zero if there was an error. If the multiplication of size and nitems overflows, i.e. the product does not fit in a size_t, then nothing is written, zero is returned, and the error state is set to Z_STREAM_ERROR.

@return

unsigned long

@see third_party/zlib/zlib.h

gzgetc

Reads one byte from the compressed file. gzgetc returns this byte or -1 in case of end of file or error. This is implemented as a macro for speed. As such, it does not do all of the checking the other functions do. I.e. it does not check to see if file is NULL, nor whether the structure file points to has been clobbered or not.

@return

int

@see third_party/zlib/zlib.h

gzgets

Reads bytes from the compressed file until len-1 characters are read, or a newline character is read and transferred to buf, or an end-of-file condition is encountered. If any characters are read or if len == 1, the string is terminated with a null character. If no characters are read due to an end-of-file or len < 1, then the buffer is left untouched.

@return

char*: buf which is a null-terminated string, or it returns NULL for end-of-file or in case of error. If there was an error, the contents at buf are indeterminate.

@see third_party/zlib/zlib.h

gzoffset

Returns current offset in the file being read or written. This offset includes the count of bytes that precede the gzip stream, for example when appending or when using gzdopen() for reading. When reading, the offset does not include as yet unused buffered input. This information can be used for a progress indicator. On error, gzoffset() returns -1.

@return

long

@see third_party/zlib/zlib.h

gzopen

Opens a gzip (.gz) file for reading or writing.

The mode parameter is as in fopen ("rb" or "wb") but can also include a compression level ("wb9") or a strategy: 'f' for filtered data as in "wb6f", 'h' for Huffman-only compression as in "wb1h", 'R' for run-length encoding as in "wb1R", or 'F' for fixed code compression as in "wb9F". (See the description of deflateInit2 for more information about the strategy parameter.) 'T' will request transparent writing or appending with no compression and not using the gzip format.

"a" can be used instead of "w" to request that the gzip stream that will be written be appended to the file. "+" will result in an error, since reading and writing to the same gzip file is not supported. The addition of "x" when writing will create the file exclusively, which fails if the file already exists. On systems that support it, the addition of "e" when reading or writing will set the flag to close the file on an execve() call.

These functions, as well as gzip, will read and decode a sequence of gzip streams in a file. The append function of gzopen() can be used to create such a file. (Also see gzflush() for another way to do this.) When appending, gzopen does not test whether the file begins with a gzip stream, nor does it look for the end of the gzip streams to begin appending. gzopen will simply append a gzip stream to the existing file.

gzopen can be used to read a file which is not in gzip format; in this case gzread will directly read from the file without decompression. When reading, this will be detected automatically by looking for the magic two- byte gzip header.

@return

struct gzFile_s*: Z_OK if the file could not be opened, if there was insufficient memory to allocate the gzFile state, or if an invalid mode was specified (an 'r', 'w', or 'a' was not provided, or '+' was provided). errno can be checked to determine if the reason gzopen failed was that the file could not be opened.

@see third_party/zlib/zlib.h

gzprintf

Converts, formats, and writes the arguments to the compressed file under control of the format string, as in fprintf. gzprintf returns the number of uncompressed bytes actually written, or a negative zlib error code in case of error. The number of uncompressed bytes written is limited to 8191, or one less than the buffer size given to gzbuffer(). The caller should assure that this limit is not exceeded. If it is exceeded, then gzprintf() will return an error (0) with nothing written. In this case, there may also be a buffer overflow with unpredictable consequences, which is possible only if zlib was compiled with the insecure functions sprintf() or vsprintf() because the secure snprintf() or vsnprintf() functions were not available. This can be determined using zlibCompileFlags().

@param

...

@return

int

@see third_party/zlib/zlib.h

gzputc

Writes character converted to an unsigned char into compressed file.

@return

int: value that was written, or -1 on error

@see third_party/zlib/zlib.h

gzputs

Writes the given null-terminated string to the compressed file, excluding the terminating null character.

@return

int: Z_OK number of characters written, or -1 in case of error.

@see third_party/zlib/zlib.h

gzread

Reads given number of uncompressed bytes from the compressed file. If the input file is not in gzip format, gzread copies the given number of bytes into the buffer directly from the file.

After reaching the end of a gzip stream in the input, gzread will continue to read, looking for another gzip stream. Any number of gzip streams may be concatenated in the input file, and will all be decompressed by gzread(). If something other than a gzip stream is encountered after a gzip stream, that remaining trailing garbage is ignored (and no error is returned).

gzread can be used to read a gzip file that is being concurrently written. Upon reaching the end of the input, gzread will return with the available data. If the error code returned by gzerror is Z_OK or Z_BUF_ERROR, then gzclearerr can be used to clear the end of file indicator in order to permit gzread to be tried again. Z_OK indicates that a gzip stream was completed on the last gzread. Z_BUF_ERROR indicates that the input file ended in the middle of a gzip stream. Note that gzread does not return -1 in the event of an incomplete gzip stream. This error is deferred until gzclose(), which will return Z_BUF_ERROR if the last gzread ended in the middle of a gzip stream. Alternatively, gzerror can be used before gzclose to detect this case.

@return

int: Z_OK number of uncompressed bytes actually read, less than len for end of file, or -1 for error. If len is too large to fit in an int, then nothing is read, -1 is returned, and the error state is set to Z_STREAM_ERROR.

@see third_party/zlib/zlib.h

gzrewind

Rewinds file.

This function is supported only for reading.

@return

int

@note gzrewind(file) is equivalent to (int)gzseek(file, 0L, SEEK_SET)

@see third_party/zlib/zlib.h

gzseek

Sets starting position for the next gzread or gzwrite on the given compressed file. The offset represents a number of bytes in the uncompressed data stream. The whence parameter is defined as in lseek(2); the value SEEK_END is not supported.

If the file is opened for reading, this function is emulated but can be extremely slow. If the file is opened for writing, only forward seeks are supported; gzseek then compresses a sequence of zeroes up to the new starting position.

@return

long: resulting offset location as measured in bytes from the beginning of the uncompressed stream, or -1 in case of error, in particular if the file is opened for writing and the new starting position would be before the current position.

@see third_party/zlib/zlib.h

gzsetparams

Dynamically update the compression level or strategy. See the description of deflateInit2 for the meaning of these parameters. Previously provided data is flushed before the parameter change.

@return

int: Z_OK if success, Z_STREAM_ERROR if the file was not opened for writing, Z_ERRNO if there is an error writing the flushed data, or Z_MEM_ERROR if there is a memory allocation error.

@see third_party/zlib/zlib.h

gztell

Returns starting position for the next gzread or gzwrite on the given compressed file. This position represents a number of bytes in the uncompressed data stream, and is zero when starting, even if appending or reading a gzip stream from the middle of a file using gzdopen().

@return

long

@note gztell(file) is equivalent to gzseek(file, 0L, SEEK_CUR)

@see third_party/zlib/zlib.h

gzungetc

Pushes one character back onto the stream to be read as the first character on the next read. At least one character of push-back is allowed. gzungetc() returns the character pushed, or -1 on failure. gzungetc() will fail if c is -1, and may fail if a character has been pushed but not read yet. If gzungetc is used immediately after gzopen or gzdopen, at least the output buffer size of pushed characters is allowed. (See gzbuffer above.) The pushed character will be discarded if the stream is repositioned with gzseek() or gzrewind().

@return

int

@see third_party/zlib/zlib.h

gzwrite

Writes given number of uncompressed bytes into the compressed file. gzwrite returns the number of uncompressed bytes written or 0 in case of error.

@return

int

@see third_party/zlib/zlib.h

h_errno

Error number global for gethostbyname*(), gethostbyaddr*(), etc.

@type

int

@see libc/dns/h_errno.c

_hamming

Counts number of different bits.

@param

unsigned long x
unsigned long y

@return

unsigned long

@see https://en.wikipedia.org/wiki/Hamming_code

@see libc/intrin/hamming.c

HasControlCodes

Returns true if C0 or C1 control codes are present

@param

const char* p: is input value
unsigned long n: if -1 implies strlen
int f: can have kControlWs, kControlC0, kControlC1 to forbid

@return

long: index of first forbidden character or -1

@see VisualizeControlCodes()

@see net/http/hascontrolcodes.c

hasmntopt

@param

struct mnt* mnt
const char* opt

@return

char*

@see third_party/musl/mntent.c

_have_fsgsbase

Returns true if FSGSBASE ISA can be used.

If this function returns true (Linux 5.9+ or FreeBSD) then you should be able to read/write to the %gs / %fs x86 segment registers in about one or two clock cycles which gives you a free addition operation for all assembly ops that reference memory.

The FSGSBASE ISA was introduced by Intel with Ivybridge (c. 2012) but the Linux Kernel didn't authorize us to use it until 2020, once Intel had to start backdooring customer kernels so that they could have it. AMD introduced support for the FSGSBASE ISA in Excavator, aka bdver4.

@return

int: boolean indicating if feature can be used

@see _rdfsbase()

@see _rdgsbase()

@see _wrfsbase()

@see _wrgsbase()

@see libc/intrin/have_fsgsbase.c

HeaderHas

Returns true if standard header has substring.

@param

struct HttpMessage* m: is message parsed by ParseHttpMessage
const char* b: is buffer that ParseHttpMessage parsed
int h: is known header, e.g. kHttpAcceptEncoding
const char* s: should not contain comma
unsigned long n: is byte length of s where -1 implies strlen

@return

_Bool: true if substring present

@see net/http/headerhassubstring.c

heapsort

Sorts array.

Runs in O (N lg N), both average and worst. While heapsort is faster than the worst case of quicksort, the BSD quicksort does median selection so that the chance of finding a data set that will trigger the worst case is nonexistent. Heapsort's only advantage over quicksort is that it requires little additional memory.

@param

void* vbase: is base of array
unsigned long nmemb: is item count
unsigned long size: is item width
int(*)() compar: is a callback returning <0, 0, or >0

@return

int

@see Knuth, Vol. 3, page 145.

@see heapsort_r()

@see mergesort()

@see qsort()

@see libc/mem/heapsort.c

heapsort_r

Sorts array w/ optional callback argument.

@param

void* vbase: is base of array
unsigned long nmemb: is item count
unsigned long size: is item width
int(*)() compar: is a callback returning <0, 0, or >0
void* z: will optionally be passed as the third argument to cmp

@return

int

@see heapsort()

@see libc/mem/heapsort.c

herror

Prints h_errno description to stderr.

@param

const char* s

@return

void

@see perror()

@see libc/dns/herror.c

hexpcpy

Turns data into lowercase hex.

This routine always writes a nul terminator, even if n is zero. There's no failure condition for this function.

@param

char* s: must have n*2+1 bytes
void* p: must have n bytes
unsigned long n: is byte length of p

@return

char*: pointer to nul byte in s

@see libc/str/hexpcpy.c

hextoint

Converts ASCII hexadecimal character to integer case-insensitively.

@param

int c

@return

int: integer or 0 if c ∉ [0-9A-Fa-f]

@see libc/str/hextoint.c

HighwayHash64

Computes Highway Hash.

highwayhash64 n=0                  121 nanoseconds
highwayhash64 n=8                   16 ns/byte         59,865 kb/s
highwayhash64 n=31                   4 ns/byte            222 mb/s
highwayhash64 n=32                   3 ns/byte            248 mb/s
highwayhash64 n=63                   2 ns/byte            387 mb/s
highwayhash64 n=64                   2 ns/byte            422 mb/s
highwayhash64 n=128                  1 ns/byte            644 mb/s
highwayhash64 n=256                  1 ns/byte            875 mb/s
highwayhash64 n=22851              721 ps/byte          1,354 mb/s

@param

void* data
unsigned long size
const unsigned long* key

@return

unsigned long

@see libc/str/highwayhash64.c

hilbert

Generates Hilbert space-filling curve.

@param

long n
long y
long x

@return

long

@see https://en.wikipedia.org/wiki/Hilbert_curve

@see unhilbert()

@see libc/intrin/hilbert.c

__hook

Rewrites code in memory to hook function calls.

We do this by searching each function for the nop instruction inserted by GCC when we use the -pg -mnop-mcount flags. There's no risk of corrupting data since the linker scripts won't mix code and data.

Modules built with -O3 and without the profiling flags might have these same nop instructions, but that shouldn't be problematic since they're only there for the puposes of aligning jumps, and therefore aren't actually executed. However codebases that use huge function alignments with wide-nop slides could pose minor issues. Further note that Cosmopolitan sources are almost never intentionally written to use code alignment, since we've only seen a few cases where it helps.

@param

void* ifunc
struct SymbolTable* symbols

@return

int

@see ape/ape.lds

@see libc/runtime/hook.greg.c

hstrerror

Turns h_errno value into string.

@param

int err

@return

const char*

@see libc/dns/hstrerror.c

htonl

Converts network to host short.

@param

unsigned int x

@return

unsigned int

@see libc/sock/htonl.c

htons

Converts host to network short.

@param

unsigned short x

@return

unsigned short

@see libc/sock/htons.c

hypot

Returns euclidean distance.

@param

double x
double y

@return

double

@see libc/tinymath/hypot.c

hypotf

@param

float x
float y

@return

float

@see libc/tinymath/hypotf.c

hypotl

@param

long double x
long double y

@return

long double

@see libc/tinymath/hypotl.c

i128abs

@param

__int128 x

@return

__int128

@see libc/fmt/i128abs.c

iconv

@param

void* cd
char** in
unsigned long* inb
char** out
unsigned long* outb

@return

unsigned long

@see libc/stdio/iconv.c

iconv_close

@param

void* cd

@return

int

@see libc/stdio/iconv.c

iconv_open

@param

const char* to
const char* from

@return

void*

@see libc/stdio/iconv.c

identity

The identity() function.

@return

: first argument

@see libc/nexgen32e/identity.S

ilogb

Returns log₂𝑥 exponent part of double.

@param

𝑥: is double passed in %xmm0

@return

: result in %eax

@note needs sse3

@see libc/tinymath/ilogb.S

ilogbf

Returns log₂x exponent part of float.

@param

𝑥: is float passed in %xmm0

@return

: result in %eax

@note needs sse3

@see libc/tinymath/ilogbf.S

ilogbl

Returns log₂x exponent part of long double.

@param

𝑥: is long double passed on stack

@return

: result in %eax

@note needs sse3

@see libc/tinymath/ilogbl.S

imapxlatab

Identity maps 256-byte translation table.

@param

char: (*rdi)[256]

@return

@speed 90mBps

@mode long

@see libc/nexgen32e/imapxlatab.S

imaxabs

@param

long x

@return

long

@see libc/fmt/imaxabs.c

imaxdiv

@param

long n
long d

@return

struct retval

@see libc/fmt/imaxdiv.c

IndentLines

Inserts spaces before lines.

@param

const char* p: is input value
unsigned long n: if -1 implies strlen
unsigned long* z: if non-NULL receives output length
unsigned long j: is number of spaces to use

@return

char*: allocated NUL-terminated buffer, or NULL w/ errno

@see net/http/indentlines.c

index

Returns pointer to first instance of character, the BSD way.

@param

const char* s: is a NUL-terminated string
int c

@return

char*: is pointer to first instance of c or NULL if not found, noting that c being NUL will return a pointer to terminator

@see libc/str/index.c

IndexDoubleNulString

@param

const char* s
unsigned int i

@return

const char*

@see libc/str/indexdoublenulstring.c

inet_addr

Converts dotted IPv4 address string to network order binary.

@param

const char* s

@return

unsigned int

@see inet_aton()

@see libc/sock/inet_addr.c

inet_aton

Converts dotted IPv4 address string to network order binary.

@param

const char* s0
ANONYMOUS-STRUCT* dest

@return

int

@see libc/sock/inet_aton.c

inet_ntoa

Converts IPv4 network address to array.

@param

struct in in

@return

char*

@see libc/sock/inet_ntoa.c

inet_ntop

Formats internet address to string.

@param

int af: can be AF_INET or AF_INET6
void* src: is the binary-encoded address, e.g. &addr->sin_addr
char* dst: is the output string buffer
unsigned int size: needs to be 16+ for IPv4 and 46+ for IPv6

@return

const char*: dst on success or NULL w/ errno

@see libc/sock/inet_ntop.c

inet_pton

Converts internet address string to binary.

@param

int af: can be AF_INET or AF_INET6
const char* src: is the ASCII-encoded address
void* dst: is where the binary-encoded net-order address goes

@return

int: 1 on success, 0 on src malformed, or -1 w/ errno

@see libc/sock/inet_pton.c

inflate

inflate decompresses as much data as possible, and stops when the input buffer becomes empty or the output buffer becomes full. It may introduce some output latency (reading input without producing any output) except when forced to flush.

The detailed semantics are as follows. inflate performs one or both of the following actions:

Decompress more input starting at next_in and update next_in and avail_in accordingly. If not all input can be processed (because there is not enough room in the output buffer), then next_in and avail_in are updated accordingly, and processing will resume at this point for the next call of inflate().
Generate more output starting at next_out and update next_out and avail_out accordingly. inflate() provides as much output as possible, until there is no more input data or no more space in the output buffer (see below about the flush parameter).

Before the call of inflate(), the application should ensure that at least one of the actions is possible, by providing more input and/or consuming more output, and updating the next_* and avail_* values accordingly. If the caller of inflate() does not provide both available input and available output space, it is possible that there will be no progress made. The application can consume the uncompressed output when it wants, for example when the output buffer is full (avail_out == 0), or after each call of inflate(). If inflate returns Z_OK and with zero avail_out, it must be called again after making room in the output buffer because there might be more output pending.

The flush parameter of inflate() can be Z_NO_FLUSH, Z_SYNC_FLUSH, Z_FINISH, Z_BLOCK, or Z_TREES. Z_SYNC_FLUSH requests that inflate() flush as much output as possible to the output buffer. Z_BLOCK requests that inflate() stop if and when it gets to the next deflate block boundary. When decoding the zlib or gzip format, this will cause inflate() to return immediately after the header and before the first block. When doing a raw inflate, inflate() will go ahead and process the first block, and will return when it gets to the end of that block, or when it runs out of data.

The Z_BLOCK option assists in appending to or combining deflate streams. To assist in this, on return inflate() always sets strm->data_type to the number of unused bits in the last byte taken from strm->next_in, plus 64 if inflate() is currently decoding the last block in the deflate stream, plus 128 if inflate() returned immediately after decoding an end-of-block code or decoding the complete header up to just before the first byte of the deflate stream. The end-of-block will not be indicated until all of the uncompressed data from that block has been written to strm->next_out. The number of unused bits may in general be greater than seven, except when bit 7 of data_type is set, in which case the number of unused bits will be less than eight. data_type is set as noted here every time inflate() returns for all flush options, and so can be used to determine the amount of currently consumed input in bits.

The Z_TREES option behaves as Z_BLOCK does, but it also returns when the end of each deflate block header is reached, before any actual data in that block is decoded. This allows the caller to determine the length of the deflate block header for later use in random access within a deflate block. 256 is added to the value of strm->data_type when inflate() returns immediately after reaching the end of the deflate block header.

inflate() should normally be called until it returns Z_STREAM_END or an error. However if all decompression is to be performed in a single step (a single call of inflate), the parameter flush should be set to Z_FINISH. In this case all pending input is processed and all pending output is flushed; avail_out must be large enough to hold all of the uncompressed data for the operation to complete. (The size of the uncompressed data may have been saved by the compressor for this purpose.) The use of Z_FINISH is not required to perform an inflation in one step. However it may be used to inform inflate that a faster approach can be used for the single inflate() call. Z_FINISH also informs inflate to not maintain a sliding window if the stream completes, which reduces inflate's memory footprint. If the stream does not complete, either because not all of the stream is provided or not enough output space is provided, then a sliding window will be allocated and inflate() can be called again to continue the operation as if Z_NO_FLUSH had been used.

In this implementation, inflate() always flushes as much output as possible to the output buffer, and always uses the faster approach on the first call. So the effects of the flush parameter in this implementation are on the return value of inflate() as noted below, when inflate() returns early when Z_BLOCK or Z_TREES is used, and when inflate() avoids the allocation of memory for a sliding window when Z_FINISH is used.

If a preset dictionary is needed after this call (see inflateSetDictionary below), inflate sets strm->adler to the Adler-32 checksum of the dictionary chosen by the compressor and returns Z_NEED_DICT; otherwise it sets strm->adler to the Adler-32 checksum of all output produced so far (that is, total_out bytes) and returns Z_OK, Z_STREAM_END or an error code as described below. At the end of the stream, inflate() checks that its computed Adler-32 checksum is equal to that saved by the compressor and returns Z_STREAM_END only if the checksum is correct.

inflate() can decompress and check either zlib-wrapped or gzip-wrapped deflate data. The header type is detected automatically, if requested when initializing with inflateInit2(). Any information contained in the gzip header is not retained unless inflateGetHeader() is used. When processing gzip-wrapped deflate data, strm->adler32 is set to the CRC-32 of the output produced so far. The CRC-32 is checked against the gzip trailer, as is the uncompressed length, modulo 2^32.

@return

int: Z_OK if some progress has been made (more input processed or more output produced), Z_STREAM_END if the end of the compressed data has been reached and all uncompressed output has been produced, Z_NEED_DICT if a preset dictionary is needed at this point, Z_DATA_ERROR if the input data was corrupted (input stream not conforming to the zlib format or incorrect check value, in which case strm->msg points to a string with a more specific error), Z_STREAM_ERROR if the stream structure was inconsistent (for example next_in or next_out was Z_NULL, or the state was inadvertently written over by the application), Z_MEM_ERROR if there was not enough memory, Z_BUF_ERROR if no progress was possible or if there was not enough room in the output buffer when Z_FINISH is used. Note that Z_BUF_ERROR is not fatal, and inflate() can be called again with more input and more output space to continue decompressing. If Z_DATA_ERROR is returned, the application may then call inflateSync() to look for a good compression block if a partial recovery of the data is to be attempted.

@see third_party/zlib/zlib.h

__inflate

Decompresses raw deflate data.

This uses puff by default since it has a 2kb footprint. If zlib proper is linked, then we favor that instead, since it's faster.

@param

void* out
unsigned long outsize: needs to be known ahead of time by some other means
void* in
unsigned long insize

@return

int: 0 on success or nonzero on failure

@see libc/runtime/inflate.c

inflateBack

inflateBack() does a raw inflate with a single call using a call-back interface for input and output. This is potentially more efficient than inflate() for file i/o applications, in that it avoids copying between the output and the sliding window by simply making the window itself the output buffer. inflate() can be faster on modern CPUs when used with large buffers. inflateBack() trusts the application to not change the output buffer passed by the output function, at least until inflateBack() returns.

inflateBackInit() must be called first to allocate the internal state and to initialize the state with the user-provided window buffer. inflateBack() may then be used multiple times to inflate a complete, raw deflate stream with each call. inflateBackEnd() is then called to free the allocated state.

A raw deflate stream is one with no zlib or gzip header or trailer. This routine would normally be used in a utility that reads zip or gzip files and writes out uncompressed files. The utility would decode the header and process the trailer on its own, hence this routine expects only the raw deflate stream to decompress. This is different from the default behavior of inflate(), which expects a zlib header and trailer around the deflate stream.

inflateBack() uses two subroutines supplied by the caller that are then called by inflateBack() for input and output. inflateBack() calls those routines until it reads a complete deflate stream and writes out all of the uncompressed data, or until it encounters an error. The function's parameters and return types are defined above in the in_func and out_func typedefs. inflateBack() will call in(in_desc, &buf) which should return the number of bytes of provided input, and a pointer to that input in buf. If there is no input available, in() must return zero -- buf is ignored in that case -- and inflateBack() will return a buffer error. inflateBack() will call out(out_desc, buf, len) to write the uncompressed data buf[0..len-1]. out() should return zero on success, or non-zero on failure. If out() returns non-zero, inflateBack() will return with an error. Neither in() nor out() are permitted to change the contents of the window provided to inflateBackInit(), which is also the buffer that out() uses to write from. The length written by out() will be at most the window size. Any non-zero amount of input may be provided by in().

For convenience, inflateBack() can be provided input on the first call by setting strm->next_in and strm->avail_in. If that input is exhausted, then in() will be called. Therefore strm->next_in must be initialized before calling inflateBack(). If strm->next_in is Z_NULL, then in() will be called immediately for input. If strm->next_in is not Z_NULL, then strm->avail_in must also be initialized, and then if strm->avail_in is not zero, input will initially be taken from strm->next_in[0 .. strm->avail_in - 1].

The in_desc and out_desc parameters of inflateBack() is passed as the first parameter of in() and out() respectively when they are called. These descriptors can be optionally used to pass any information that the caller- supplied in() and out() functions need to do their job.

On return, inflateBack() will set strm->next_in and strm->avail_in to pass back any unused input that was provided by the last in() call. The return values of inflateBack() can be Z_STREAM_END on success, Z_BUF_ERROR if in() or out() returned an error, Z_DATA_ERROR if there was a format error in the deflate stream (in which case strm->msg is set to indicate the nature of the error), or Z_STREAM_ERROR if the stream was not properly initialized. In the case of Z_BUF_ERROR, an input or output error can be distinguished using strm->next_in which will be Z_NULL only if in() returned an error. If strm->next_in is not Z_NULL, then the Z_BUF_ERROR was due to out() returning non-zero. (in() will always be called before out(), so strm->next_in is assured to be defined if out() returns non-zero.) Note that inflateBack() cannot return Z_OK.

@return

int

@see third_party/zlib/zlib.h

inflateBackEnd

All memory allocated by inflateBackInit() is freed.

@return

int: Z_OK on success, or Z_STREAM_ERROR if the stream state was inconsistent.

@see third_party/zlib/zlib.h

inflateBackInit

Initialize internal stream state for decompression using inflateBack() calls. The fields zalloc, zfree and opaque in strm must be initialized before the call. If zalloc and zfree are Z_NULL, then the default library- derived memory allocation routines are used. windowBits is the base two logarithm of the window size, in the range 8..15. window is a caller supplied buffer of that size. Except for special applications where it is assured that deflate was used with small window sizes, windowBits must be 15 and a 32K byte window must be supplied to be able to decompress general deflate streams.

See inflateBack() for the usage of these routines.

@return

int: Z_OK on success, Z_STREAM_ERROR if any of the parameters are invalid, or Z_MEM_ERROR if the internal state could not be allocated.

@see third_party/zlib/zlib.h

inflateCopy

Sets the destination stream as a complete copy of the source stream.

This function can be useful when randomly accessing a large stream. The first pass through the stream can periodically record the inflate state, allowing restarting inflate at those points when randomly accessing the stream.

@return

int: Z_OK if success, Z_MEM_ERROR if there was not enough memory, Z_STREAM_ERROR if the source stream state was inconsistent (such as zalloc being Z_NULL). msg is left unchanged in both source and destination.

@see third_party/zlib/zlib.h

inflateEnd

All dynamically allocated data structures for this stream are freed. This function discards any unprocessed input and does not flush any pending output.

@return

int: Z_OK or Z_STREAM_ERROR if stream state inconsistent

@see third_party/zlib/zlib.h

inflateGetDictionary

Returns the sliding dictionary being maintained by inflate. dictLength is set to the number of bytes in the dictionary, and that many bytes are copied to dictionary. dictionary must have enough space, where 32768 bytes is always enough. If inflateGetDictionary() is called with dictionary equal to Z_NULL, then only the dictionary length is returned, and nothing is copied. Similary, if dictLength is Z_NULL, then it is not set.

@return

int: Z_OK on success, or Z_STREAM_ERROR if the stream state is inconsistent.

@see third_party/zlib/zlib.h

inflateGetHeader

inflateGetHeader() requests that gzip header information be stored in the provided gz_header structure. inflateGetHeader() may be called after inflateInit2() or inflateReset(), and before the first call of inflate(). As inflate() processes the gzip stream, head->done is zero until the header is completed, at which time head->done is set to one. If a zlib stream is being decoded, then head->done is set to -1 to indicate that there will be no gzip header information forthcoming. Note that Z_BLOCK or Z_TREES can be used to force inflate() to return immediately after header processing is complete and before any actual data is decompressed.

The text, time, xflags, and os fields are filled in with the gzip header contents. hcrc is set to true if there is a header CRC. (The header CRC was valid if done is set to one.) If extra is not Z_NULL, then extra_max contains the maximum number of bytes to write to extra. Once done is true, extra_len contains the actual extra field length, and extra contains the extra field, or that field truncated if extra_max is less than extra_len. If name is not Z_NULL, then up to name_max characters are written there, terminated with a zero unless the length is greater than name_max. If comment is not Z_NULL, then up to comm_max characters are written there, terminated with a zero unless the length is greater than comm_max. When any of extra, name, or comment are not Z_NULL and the respective field is not present in the header, then that field is set to Z_NULL to signal its absence. This allows the use of deflateSetHeader() with the returned structure to duplicate the header. However if those fields are set to allocated memory, then the application will need to save those pointers elsewhere so that they can be eventually freed.

If inflateGetHeader is not used, then the header information is simply discarded. The header is always checked for validity, including the header CRC if present. inflateReset() will reset the process to discard the header information. The application would need to call inflateGetHeader() again to retrieve the header from the next gzip stream.

@return

int: Z_OK if success, or Z_STREAM_ERROR if the source stream state was inconsistent.

@see third_party/zlib/zlib.h

inflateInit

Initializes the internal stream state for decompression. The fields next_in, avail_in, zalloc, zfree and opaque must be initialized before by the caller. In the current version of inflate, the provided input is not read or consumed. The allocation of a sliding window will be deferred to the first call of inflate (if the decompression does not complete on the first call). If zalloc and zfree are set to Z_NULL, inflateInit updates them to use default allocation functions.

@return

int: Z_OK if success, Z_MEM_ERROR if there was not enough memory, or Z_STREAM_ERROR if the parameters are invalid, such as a null pointer to the structure. msg is set to null if there is no error message. inflateInit does not perform any decompression. Actual decompression will be done by inflate(). So next_in, and avail_in, next_out, and avail_out are unused and unchanged. The current implementation of inflateInit() does not process any header information -- that is deferred until inflate() is called.

@see third_party/zlib/zlib.h

inflateInit2

This is another version of inflateInit with an extra parameter. The fields next_in, avail_in, zalloc, zfree and opaque must be initialized before by the caller.

The windowBits parameter is the base two logarithm of the maximum window size (the size of the history buffer). It should be in the range 8..15 for this version of the library. The default value is 15 if inflateInit is used instead. windowBits must be greater than or equal to the windowBits value provided to deflateInit2() while compressing, or it must be equal to 15 if deflateInit2() was not used. If a compressed stream with a larger window size is given as input, inflate() will return with the error code Z_DATA_ERROR instead of trying to allocate a larger window.

windowBits can also be zero to request that inflate use the window size in the zlib header of the compressed stream.

windowBits can also be -8..-15 for raw inflate. In this case, -windowBits determines the window size. inflate() will then process raw deflate data, not looking for a zlib or gzip header, not generating a check value, and not looking for any check values for comparison at the end of the stream. This is for use with other formats that use the deflate compressed data format such as zip. Those formats provide their own check values. If a custom format is developed using the raw deflate format for compressed data, it is recommended that a check value such as an Adler-32 or a CRC-32 be applied to the uncompressed data as is done in the zlib, gzip, and zip formats. For most applications, the zlib format should be used as is. Note that comments above on the use in deflateInit2() applies to the magnitude of windowBits.

windowBits can also be greater than 15 for optional gzip decoding. Add 32 to windowBits to enable zlib and gzip decoding with automatic header detection, or add 16 to decode only the gzip format (the zlib format will return a Z_DATA_ERROR). If a gzip stream is being decoded, strm->adler is a CRC-32 instead of an Adler-32. Unlike the gunzip utility and gzread() (see below), inflate() will not automatically decode concatenated gzip streams. inflate() will return Z_STREAM_END at the end of the gzip stream. The state would need to be reset to continue decoding a subsequent gzip stream.

@return

int: Z_OK if success, Z_MEM_ERROR if there was not enough memory, or Z_STREAM_ERROR if the parameters are invalid, such as a null pointer to the structure. msg is set to null if there is no error message. inflateInit2 does not perform any decompression apart from possibly reading the zlib header if present: actual decompression will be done by inflate(). (So next_in and avail_in may be modified, but next_out and avail_out are unused and unchanged.) The current implementation of inflateInit2() does not process any header information -- that is deferred until inflate() is called.

@see third_party/zlib/zlib.h

inflateMark

Returns two values, one in the lower 16 bits of the return value, and the other in the remaining upper bits, obtained by shifting the return value down 16 bits. If the upper value is -1 and the lower value is zero, then inflate() is currently decoding information outside of a block. If the upper value is -1 and the lower value is non-zero, then inflate is in the middle of a stored block, with the lower value equaling the number of bytes from the input remaining to copy. If the upper value is not -1, then it is the number of bits back from the current bit position in the input of the code (literal or length/distance pair) currently being processed. In that case the lower value is the number of bytes already emitted for that code.

A code is being processed if inflate is waiting for more input to complete decoding of the code, or if it has completed decoding but is waiting for more output space to write the literal or match data.

inflateMark() is used to mark locations in the input data for random access, which may be at bit positions, and to note those cases where the output of a code may span boundaries of random access blocks. The current location in the input stream can be determined from avail_in and data_type as noted in the description for the Z_BLOCK flush parameter for inflate.

@return

long: the value noted above, or -65536 if the provided source stream state was inconsistent.

@see third_party/zlib/zlib.h

inflatePrime

This function inserts bits in the inflate input stream. The intent is that this function is used to start inflating at a bit position in the middle of a byte. The provided bits will be used before any bytes are used from next_in. This function should only be used with raw inflate, and should be used before the first inflate() call after inflateInit2() or inflateReset(). bits must be less than or equal to 16, and that many of the least significant bits of value will be inserted in the input.

If bits is negative, then the input stream bit buffer is emptied. Then inflatePrime() can be called again to put bits in the buffer. This is used to clear out bits leftover after feeding inflate a block description prior to feeding inflate codes.

@return

int: Z_OK if success, or Z_STREAM_ERROR if the source stream state was inconsistent.

@see third_party/zlib/zlib.h

inflateReset

This function is equivalent to inflateEnd followed by inflateInit, but does not free and reallocate the internal decompression state. The stream will keep attributes that may have been set by inflateInit2.

@return

int: Z_OK if success, or Z_STREAM_ERROR if the source stream state was inconsistent (such as zalloc or state being Z_NULL).

@see third_party/zlib/zlib.h

inflateReset2

This function is the same as inflateReset, but it also permits changing the wrap and window size requests. The windowBits parameter is interpreted the same as it is for inflateInit2. If the window size is changed, then the memory allocated for the window is freed, and the window will be reallocated by inflate() if needed.

@return

int: Z_OK if success, or Z_STREAM_ERROR if the source stream state was inconsistent (such as zalloc or state being Z_NULL), or if the windowBits parameter is invalid.

@see third_party/zlib/zlib.h

inflateSetDictionary

Initializes the decompression dictionary from the given uncompressed byte sequence. This function must be called immediately after a call of inflate, if that call returned Z_NEED_DICT. The dictionary chosen by the compressor can be determined from the Adler-32 value returned by that call of inflate. The compressor and decompressor must use exactly the same dictionary (see deflateSetDictionary). For raw inflate, this function can be called at any time to set the dictionary. If the provided dictionary is smaller than the window and there is already data in the window, then the provided dictionary will amend what's there. The application must insure that the dictionary that was used for compression is provided.

@return

int: Z_OK if success, Z_STREAM_ERROR if a parameter is invalid (e.g. dictionary being Z_NULL) or the stream state is inconsistent, Z_DATA_ERROR if the given dictionary doesn't match the expected one (incorrect Adler-32 value). inflateSetDictionary does not perform any decompression: this will be done by subsequent calls of inflate().

@see third_party/zlib/zlib.h

inflateSync

Skips invalid compressed data until a possible full flush point (see above for the description of deflate with Z_FULL_FLUSH) can be found, or until all available input is skipped. No output is provided.

inflateSync searches for a 00 00 FF FF pattern in the compressed data. All full flush points have this pattern, but not all occurrences of this pattern are full flush points.

@return

int: Z_OK if a possible full flush point has been found, Z_BUF_ERROR if no more input was provided, Z_DATA_ERROR if no flush point has been found, or Z_STREAM_ERROR if the stream structure was inconsistent. In the success case, the application may save the current current value of total_in which indicates where valid compressed data was found. In the error case, the application may repeatedly call inflateSync, providing more input each time, until success or end of the input data.

@see third_party/zlib/zlib.h

_init

Decentralized function for process initialization.

Modules may inject cheap data structure initialization code into this function using the .init.start and .init.end macros. That code can use the LODS and STOS instructions to initialize memory that's restricted to read-only after initialization by PIRO.

This is fast, since the linker is able to roll-up initialization for large codebases comprised of many modules, into a perfectly linear order. It also enables a common pattern we use, which we call “Referencing Is Initialization” (RII).

C/C++ code should favor using ordinary constructors, since under normal circumstances the compiler will clobber RDI and RSI which are granted special meanings within this function.

@param

r12: is argc (still callee saved)
r13: is argv (still callee saved)
r14: is envp (still callee saved)
r15: is envp (still callee saved)

@return

@note rdi is __init_bss_start (callee monotonic lockstep)

@note rsi is __init_rodata_start (callee monotonic lockstep)

@see .init.start & .init.end (libc/macros.internal.h)

@see ape/ape.lds

@see libc/runtime/init.S

__init_bss_start

Decentralized section for unpacked data structures.

Data in this section becomes read-only after initialization.

@return

@see .piro.bss.init (libc/macros.internal.h)

@see libc/runtime/piro.c

@see ape/ape.lds

@see libc/runtime/init.S

init_mparams

@return

int

@see third_party/dlmalloc/init.inc

__init_rodata_start

Decentralized section for packed data structures & initializers.

@return

@see .initro (libc/macros.internal.h)

@see ape/ape.lds

@see libc/runtime/init.S

InitHttpMessage

Initializes HTTP message parser.

@param

struct HttpMessage* r
int type

@return

void

@see net/http/parsehttpmessage.c

InitializeFileDescriptors

@return

void

@see libc/intrin/g_fds.c

InitializeMetalFile

@return

void

@see libc/calls/metalfile.c

initstate

@param

unsigned int seed
char* state
unsigned long size

@return

char*

@see libc/stdio/random.c

InsertInt

@param

struct SortedInts* t
int k
_Bool u

@return

_Bool

@see libc/mem/sortedints.c

int128toarray_radix10

Converts signed 128-bit integer to string.

@param

__int128 i
char* a: needs at least 41 bytes

@return

unsigned long: bytes written w/o nul

@see libc/fmt/itoa128radix10.greg.c

int64toarray

@param

long i
char* a
int r

@return

unsigned long

@see libc/fmt/itoa64.c

_intsort

Tiny and reasonably fast sorting for ints.

@param

int* A
unsigned long n

@return

void

@see djbsort

@see libc/str/intsort.c

__invert_memory_area

Identity maps an area of physical memory to its negative address.

@param

struct mman* mm
unsigned long* pml4t
unsigned long ps
unsigned long size
unsigned long pte_flags

@return

unsigned long*

@see libc/intrin/mman.greg.c

ioctl

Controls settings on device.

@param

int fd
unsigned long request
...

@return

int

@restartable

@vforksafe

@see libc/calls/ioctl.c

__iovec2nt

Converts I/O vector from System Five to WIN32 ABI.

@param

struct ProviderSpecific* iovnt
struct iovec* iov
unsigned long iovlen

@return

unsigned long: effective iovlen

@see IOV_MAX

@see libc/sock/iovec2nt.c

_isabspath

Returns true if pathname is considered absolute.

/home/jart/foo.txt is absolute
C:/Users/jart/foo.txt is absolute on Windows
C:\Users\jart\foo.txt is absolute on Windows
\??\C:\Users\jart\foo.txt is absolute on Windows
\\.\C:\Users\jart\foo.txt is absolute on Windows
/Users/jart/foo.txt is effectively absolute on Windows
\Users\jart\foo.txt is effectively absolute on Windows

@param

const char* path

@return

_Bool

@see libc/str/isabspath.c

IsAcceptableHost

Returns true if host seems legit.

This function may be called after ParseUrl() or ParseHost() has already handled things like percent encoding. There's currently no support for IPv6 and IPv7.

Here's examples of permitted inputs:

""
1.2.3.4
1.2.3.4.arpa
localservice
hello.example
_hello.example
-hello.example
hi-there.example

Here's some examples of forbidden inputs:

::1
1.2.3
1.2.3.4.5
.hi.example
hi..example

@param

const char* s
unsigned long n: if -1 implies strlen

@return

_Bool

@see net/http/isacceptablehost.c

IsAcceptablePath

Returns true if path seems legit.

The substring "//" is disallowed.
We won't serve hidden files (segment starts with '.'). The only exception is /.well-known/.
We won't serve paths with segments equal to "." or "..".

It is assumed that the URI parser already took care of percent escape decoding as well as ISO-8859-1 decoding. The input needs to be a UTF-8 string. This function takes overlong encodings into consideration, so you don't need to call Underlong() beforehand.

@param

const char* data
unsigned long size: if -1 implies strlen

@return

_Bool

@see IsReasonablePath()

@see net/http/isacceptablepath.c

IsAcceptablePort

Returns true if port seems legit.

Here's examples of permitted inputs:

""
0
65535

Here's some examples of forbidden inputs:

-1
65536
https

@param

const char* s
unsigned long n: if -1 implies strlen

@return

_Bool

@see net/http/isacceptableport.c

IsAfrinicIp

Returns true if IPv4 address is managed by AFRINIC.

@param

unsigned int x

@return

_Bool

@see net/http/isafrinicip.c

isalnum

Returns nonzero if c is lower, alpha, or digit.

@param

int c

@return

int

@see libc/str/isalnum.c

isalpha

Returns nonzero if c is upper or lower.

@param

int c

@return

int

@see libc/str/isalpha.c

IsAnonymousIp

Returns true if IPv4 address is anonymous proxy provider.

@param

unsigned int x

@return

_Bool

@see net/http/isanonymousip.c

IsAPEMagic

@param

char* buf

@return

_Bool

@see libc/calls/execve-sysv.c

IsApnicIp

Returns true if IPv4 address is managed by APNIC.

@param

unsigned int x

@return

_Bool

@see net/http/isapnicip.c

IsArinIp

Returns true if IPv4 address is managed by ARIN.

@param

unsigned int x

@return

_Bool

@see net/http/isarinip.c

isascii

Returns nonzero if c is ascii.

@param

int c

@return

int

@see libc/str/isascii.c

IsAtLeastWindows10

Returns true if we're running at least Windows 10.

This function may only be called if IsWindows() is true.

@return

_Bool

@see libc/intrin/isatleastwindows10.greg.c

isatty

Tells if file descriptor is a terminal.

@param

int fd: is file descriptor

@return

int: 1 if is terminal, otherwise 0 w/ errno

@raise EBADF if fd isn't a valid file descriptor

@raise ENOTTY if fd is something other than a terminal

@raise EPERM if pledge() was used without tty

@see libc/calls/isatty.c

isblank

Returns nonzero if c is space or tab.

@param

int c

@return

int

@see libc/str/isblank.c

ischardev

Returns true if file descriptor is backed by character i/o.

This function is equivalent to:

struct stat st;
return stat(path, &st) != -1 && S_ISCHR(st.st_mode);

Except faster and with fewer dependencies.

@param

int fd

@return

int

@see isregularfile(), isdirectory(), issymlink(), fileexists()

@see libc/calls/ischardev.c

IsCloudflareIp

Returns true if x is Cloudflare IPv4 address.

@param

unsigned int x

@return

_Bool

@see https://www.cloudflare.com/ips/ (April 8, 2021)

@see net/http/iscloudflare.c

iscntrl

Returns nonzero if c is C0 ASCII control code or DEL.

@param

int c

@return

int

@see libc/str/iscntrl.c

IsCygwin

@return

_Bool

@see libc/intrin/iscygwin.c

IsDebuggerPresent

Determines if gdb, strace, windbg, etc. is controlling process.

@param

_Bool force

@return

int: non-zero if attached, otherwise 0

@see libc/intrin/isdebuggerpresent.c

isdigit

Returns nonzero if c is decimal digit.

@param

int c

@return

int

@see libc/str/isdigit.c

isdigit_l

@param

int c
struct __locale_struct* l

@return

int

@see libc/str/isdigit_l.c

isdirectory

Returns true if file exists and is a directory.

This function is equivalent to:

struct stat st;
return fstatat(AT_FDCWD, path, &st, AT_SYMLINK_NOFOLLOW) != -1 &&
       S_ISDIR(st.st_mode);

Except faster, with fewer dependencies, and less errno clobbering.

@param

const char* path

@return

_Bool

@see isregularfile(), issymlink(), ischardev()

@see libc/calls/isdirectory.c

isdirectory_nt

Returns true if file exists and is a directory on Windows NT.

@param

const char* path

@return

_Bool

@see libc/calls/isdirectory-nt.c

_isdirsep

Returns true if character is directory separator slash.

@param

int c

@return

_Bool

@see libc/str/isdirsep.c

IsDodIp

Returns true if IP is owned by the U.S. Department of Defense.

@param

unsigned int x

@return

_Bool

@see net/http/isdodip.c

IsDynamicExecutable

Returns true if ELF executable uses dynamic loading magic.

@param

const char* prog

@return

_Bool

@see libc/runtime/isdynamicexecutable.c

IsElf64Binary

@param

struct Elf64_Ehdr* elf
unsigned long mapsize

@return

_Bool

@see libc/elf/iself64binary.c

IsElfSymbolContent

@param

struct Elf64_Sym* sym

@return

_Bool

@see libc/elf/iselfsymbolcontent.c

isexecutable

Returns true if file exists and is executable.

@param

const char* path

@return

_Bool

@see access(exe, X_OK) which is more accurate on NT

@asyncsignalsafe

@vforksafe

@see libc/calls/isexecutable.c

IsGenuineBlink

@return

_Bool

@see libc/intrin/isgenuineblink.c

isgraph

Returns nonzero if c is printable ascii that isn't space.

@param

int c

@return

int

@see libc/str/isgraph.c

_isheap

Returns true if address isn't stack and was malloc'd or mmap'd.

@param

void* p

@return

_Bool

@assume stack addresses are always greater than heap addresses

@assume stack memory isn't stored beneath %rsp (-mno-red-zone)

@see libc/runtime/isheap.c

IsLacnicIp

Returns true if IPv4 address is managed by LACNIC.

@param

unsigned int x

@return

_Bool

@see net/http/islacnicip.c

IsLoopbackIp

Returns true if IPv4 address is used for localhost.

@param

unsigned int x

@return

_Bool

@see libc/intrin/isloopbackip.c

islower

Returns nonzero if c is lowercase alpha ascii character.

@param

int c

@return

int

@see libc/str/islower.c

islower_l

@param

int c
struct __locale_struct* l

@return

int

@see libc/str/islower_l.c

IsMemtracked

@param

int x
int y

@return

_Bool

@see libc/runtime/ismemtracked.greg.c

IsMimeType

Returns true if content-type 𝑡 has mime-type 𝑠.

@param

const char* t
unsigned long n
const char* s

@return

_Bool

@see net/http/ismimetype.c

IsMulticastIp

Returns true if IPv4 address is used for multicast.

@param

unsigned int x

@return

_Bool

@see net/http/ismulticastip.c

IsNoCompressExt

@param

const char* p
unsigned long n

@return

_Bool

@see net/http/isnocompressext.c

iso8601

Converts timestamp to ISO-8601 formatted string.

For example:

char *GetZuluTime(void) {
  char *p;
  struct tm tm;
  struct timespec ts;
  static _Thread_local int64_t last;
  static _Thread_local char str[21];
  clock_gettime(0, &ts);
  if (ts.tv_sec != last) {
    gmtime_r(&ts.tv_sec, &tm);
    last = ts.tv_sec;
    stpcpy(iso8601(str, &tm), "Z");
  }
  return str;
}

Will return timestamps that look like:

2020-01-01T13:14:15Z

The generated timestamp is always exactly 19 characters long. It is also always nul terminated too.

This function defines no failure conditions. The results of passing timestamp values outside of the appropriate intervals is undefined.

@param

char* p: is buffer with at least 20 bytes
struct tm* tm: has valid gmtime_r() or localtime_r() output

@return

char*: pointer to nul terminator within p, cf. stpcpy()

@see iso8601us() for microsecond timestamps

@asyncsignalsafe

@threadsafe

@see libc/time/iso8601.c

iso8601us

Converts timestamp to ISO-8601 formatted string.

For example:

char *GetTimestamp(void) {
  struct timespec ts;
  static _Thread_local struct tm tm;
  static _Thread_local int64_t last;
  static _Thread_local char str[27];
  clock_gettime(0, &ts);
  if (ts.tv_sec != last) {
    localtime_r(&ts.tv_sec, &tm);
    last = ts.tv_sec;
  }
  iso8601us(str, &tm, ts.tv_nsec);
  return str;
}

Will return timestamps that look like:

2020-01-01T13:14:15.123456

The generated timestamp is always exactly 26 characters long. It is also always nul terminated too.

This function defines no failure conditions. The results of passing timestamp, or nanosecond values outside their appropriate intervals is undefined.

This goes 19x faster than strftime().

iso8601             l:        21c         7ns
iso8601us           l:        39c        13ns
strftime            l:       779c       252ns

@param

char* p: is buffer with at least 20 bytes
struct tm* tm: has valid gmtime_r() or localtime_r() output
long ns: is nanosecond value associated with timestamp

@return

char*: pointer to nul terminator within p, cf. stpcpy()

@see iso8601() if microsecond resolution isn't desirable

@asyncsignalsafe

@threadsafe

@see libc/time/iso8601us.c

isprint

Returns nonzero if c is printable ascii including space.

@param

int c

@return

int

@see libc/str/isprint.c

IsPrivateIp

Returns true if IPv4 address is intended for private networks.

@param

unsigned int x

@return

_Bool

@see libc/intrin/isprivateip.c

IsPublicIp

Returns true if IPv4 address is Globally Reachable.

We intentionally omit TEST-NET here which can be used to simulate public Internet traffic using non-Internet IPs.

@param

unsigned int x

@return

_Bool: true 92.4499% of the time

@see IANA IPv4 Special-Purpose Address Registry

@see libc/intrin/ispublicip.c

ispunct

Returns nonzero if c ∈ !"#$%&'()*+,-./:;<=>?@[\]^_`{|}~

@param

int c

@return

int

@see libc/str/ispunct.c

IsReasonablePath

Returns true if path doesn't contain "." or ".." segments.

@param

const char* data
unsigned long size: if -1 implies strlen

@return

_Bool

@see IsAcceptablePath()

@see net/http/isreasonablepath.c

isregularfile

Returns true if file exists and is a regular file.

This function is equivalent to:

return fstatat(AT_FDCWD, path, &st, AT_SYMLINK_NOFOLLOW) != -1 &&
       S_ISREG(st.st_mode);

Except faster, with fewer dependencies, and less errno clobbering.

@param

const char* path

@return

_Bool

@see isdirectory(), ischardev(), issymlink()

@see libc/calls/isregularfile.c

isregularfile_nt

Returns true if file exists and is a regular file on Windows NT.

@param

const char* path

@return

_Bool

@see libc/calls/isregularfile-nt.c

IsRipeIp

Returns true if IPv4 address is managed by RIPE NCC.

@param

unsigned int x

@return

_Bool

@see net/http/isripeip.c

IsRunningUnderMake

Returns true if current process was spawned by GNU Make.

@return

_Bool

@see libc/intrin/isrunningundermake.c

issetugid

Determines if process is tainted.

This function returns 1 if process was launched as a result of an execve() call on a binary that had the setuid or setgid bits set. FreeBSD defines tainted as including processes that changed their effective user / group ids at some point.

@return

int: always successful, 1 if yes, 0 if no

@see libc/calls/issetugid.c

isspace

Returns nonzero if c is space, \t, \r, \n, \f, or \v.

@param

int c

@return

int

@see isblank()

@see libc/str/isspace.c

issymlink

Returns true if file exists and is a symbolic link.

This function is equivalent to:

struct stat st;
return fstatat(AT_FDCWD, path, &st, AT_SYMLINK_NOFOLLOW) != -1 &&
       S_ISLNK(st.st_mode);

Except faster and with fewer dependencies.

@param

const char* path

@return

_Bool

@see isregularfile(), isdirectory(), fileexists(), ischardev()

@see libc/calls/issymlink.c

issymlink_nt

Returns true if file exists and is a symbolic link on Windows NT.

@param

const char* path

@return

_Bool

@see libc/calls/issymlink-nt.c

IsTestnetIp

Returns true if IPv4 address is intended for documentation.

@param

unsigned int x

@return

_Bool

@see RFC5737

@see net/http/istestnetip.c

_istext

Returns true if buffer is most likely plaintext.

@param

void* data
unsigned long size

@return

_Bool

@see libc/str/istext.c

isupper

Returns nonzero if c is uppercase alpha ascii character.

@param

int c

@return

int

@see libc/str/isupper.c

isupper_l

@param

int c
struct __locale_struct* l

@return

int

@see libc/str/isupper_l.c

IsValidCookieValue

Returns true if string is a valid cookie value (any ASCII excluding control char, whitespace, double quotes, comma, semicolon, and backslash).

@param

const char* s
unsigned long n: if -1 implies strlen

@return

_Bool

@see net/http/isvalidcookievalue.c

IsValidHttpToken

Returns true if string is ASCII without delimiters.

@param

const char* s
unsigned long n: if -1 implies strlen

@return

_Bool

@see net/http/isvalidhttptoken.c

iswalnum

Returns nonzero if c is lower, alpha, or digit.

@param

unsigned int c

@return

int

@see libc/str/iswalnum.c

iswalpha

Returns nonzero if c is alphabetical.

@param

unsigned int c

@return

int

@see libc/str/iswalpha.c

iswalpha_l

@param

unsigned int c
struct __locale_struct* l

@return

int

@see libc/str/iswalpha_l.c

iswblank

Returns nonzero if c is space or tab.

@param

unsigned int c

@return

int

@see libc/str/iswblank.c

iswblank_l

@param

unsigned int c
struct __locale_struct* l

@return

int

@see libc/str/iswblank_l.c

iswcntrl

Returns nonzero if c is C0 or C1 control code.

@param

unsigned int c

@return

int

@see libc/str/iswcntrl.c

iswcntrl_l

@param

unsigned int c
struct __locale_struct* l

@return

int

@see libc/str/iswcntrl_l.c

iswctype

Returns nonzero if c has property.

@param

unsigned int c
unsigned int t: is number returned by wctype

@return

int

@see libc/str/iswctype.c

iswdigit

Returns nonzero if c is decimal digit.

@param

unsigned int c

@return

int

@see libc/str/iswdigit.c

iswdigit_l

@param

unsigned int c
struct __locale_struct* l

@return

int

@see libc/str/iswdigit_l.c

iswgraph

Returns nonzero if c is printable and not a space.

@param

unsigned int c

@return

int

@see libc/str/iswgraph.c

iswlower

Returns nonzero if c is lowercase letter.

@param

unsigned int c

@return

int

@see libc/str/iswlower.c

iswlower_l

@param

unsigned int c
struct __locale_struct* l

@return

int

@see libc/str/iswlower_l.c

__isworker

Indicates if current execution context is a worker task.

Setting this to true on things like the forked process of a web server is a good idea since it'll ask the C runtime to not pull magical stunts like attaching GDB to the process on crash.

@type

_Bool

@see libc/intrin/isworker.c

iswprint

Returns nonzero if c is printable.

@param

unsigned int c

@return

int

@see libc/str/iswprint.c

iswprint_l

@param

unsigned int c
struct __locale_struct* l

@return

int

@see libc/str/iswprint_l.c

iswpunct

Returns nonzero if c is punctuation mark.

@param

unsigned int c

@return

int

@see libc/str/iswpunct.c

iswpunct_l

@param

unsigned int c
struct __locale_struct* l

@return

int

@see libc/str/iswpunct_l.c

iswseparator

Returns nonzero if 𝑐 isn't alphanumeric.

Line reading interfaces generally define this operation as UNICODE characters that aren't in the letter category (Lu, Ll, Lt, Lm, Lo) and aren't in the number categorie (Nd, Nl, No). We also add a few other things like blocks and emoji (So).

@param

unsigned int c

@return

int

@see libc/str/iswseparator.c

IsWsl1

Returns true if host platform is WSL 1.0.

@return

_Bool

@see libc/intrin/iswsl.c

iswspace

Returns nonzero if c is space character.

We define this as invisible characters which move the cursor. That means \t\r\n\f\v and unicodes whose category begins with Z but not ogham since it's not invisible and non-breaking spaces neither since they're not invisible to emacs users.

@param

unsigned int c

@return

int

@see libc/str/iswspace.c

iswspace_l

@param

unsigned int c
struct __locale_struct* l

@return

int

@see libc/str/iswspace_l.c

iswupper

Returns nonzero if c is uppercase letter.

@param

unsigned int c

@return

int

@see libc/str/iswupper.c

iswupper_l

@param

unsigned int c
struct __locale_struct* l

@return

int

@see libc/str/iswupper_l.c

iswxdigit

Returns nonzero if c is ascii hex digit.

@param

unsigned int c

@return

int

@see libc/str/iswxdigit.c

iswxdigit_l

@param

unsigned int c
struct __locale_struct* l

@return

int

@see libc/str/iswxdigit_l.c

isxdigit

Returns true if c is hexadecimal digit.

@param

int c

@return

int

@see libc/str/isxdigit.c

isxdigit_l

@param

int c
struct __locale_struct* l

@return

int

@see libc/str/isxdigit_l.c

IsZipCdir32

Returns true if zip end of central directory header seems legit.

@param

const unsigned char* p
unsigned long n
unsigned long i

@return

_Bool

@see libc/str/iszipcdir32.c

IsZipCdir64

Returns true if zip64 end of central directory header seems legit.

@param

const unsigned char* p
unsigned long n
unsigned long i

@return

_Bool

@see libc/str/iszipcdir64.c

itoa

@param

int value
char* str
int radix

@return

char*

@see libc/fmt/itoa.c

_jmpstack

Switches stack.

@param

rdi: is new rsp, passed as malloc(size) + size
rsi: is function to call in new stack space
rdx,rcx,r8,r9: get passed as args to rsi

@noreturn

@see libc/runtime/jmpstack.S

_join

Waits for thread created by _spawn() to terminate.

This will free your thread's stack and tls memory too.

@param

struct ths* th

@return

int

@see libc/thread/spawn.c

_joinpaths

Joins paths, e.g.

0    + 0    → 0
""   + ""   → ""
"a"  + 0    → "a"
"a"  + ""   → "a/"
0    + "b"  → "b"
""   + "b"  → "b"
"."  + "b"  → "./b"
"b"  + "."  → "b/."
"a"  + "b"  → "a/b"
"a/" + "b"  → "a/b"
"a"  + "b/" → "a/b/"
"a"  + "/b" → "/b"

@param

char* buf
unsigned long size
const char* path
const char* other

@return

char*: joined path, which may be buf, path, or other, or null if (1) buf didn't have enough space, or (2) both path and other were null

@see libc/fmt/joinpaths.c

JoinStrList

@param

struct StrList* sl
char** buf
unsigned long sep

@return

int

@see libc/stdio/joinstrlist.c

jrand48

@param

unsigned short* s

@return

long

@see third_party/musl/rand48.c

kappendf

Appends formatted string to buffer w/ kprintf, e.g.

char *b = 0;
kappendf(&b, "hello %d\n", 123);
free(b);

@param

char** b
const char* fmt
...

@return

long: bytes appended or -1 if ENOMEM

@see appendz(b).i to get buffer length

@note O(1) amortized buffer growth

@see kprintf()

@see libc/stdio/kappendf.c

kConsoleHandles

@type

const unsigned char[3]

@see libc/intrin/restorewintty.c

kCp437

ibm cp437 unicode table w/ string literal safety

        ░▄██▒▄█ ▐██ ░░░     ▀▀████▒▀█▄
       ▐███▓██░ ██▌            ▀████▄■█▄
      ▐█▓███▀█░██▀   ░          ░▀█████▓▄
     ▐█▓██▀▄█▒██▀  ▄▄░  ▄▄▄ ░░░   ░▀████▒▄
    ▐████▀▄█■█▀      ▀▀             ░█████░
   ▐█▓█▀████▀          ░             ▐▓███▒
   █░███▀▀     ░░░    ▄█       ░░░    █████
  ▐█▓█░▀▀  ░░▄█▄▄▄▄▄  ▀▄ ▌▄▄▄░▄▄▄▄▄   ▐████░
  ▐███▌   ▄▀█████████▄ ▌▐▄████████▄   ▐▓███░
  ▐███░░░▀▄█▀▄▄████▄▀░  ▐████████▒ ▀   ░███░
  ░████░ ▓▀ ▄███████▀▌   ▀▄■████▀▀█▀   ██▀█
   ▓███░ ░▄▀▀░░░ ▀  ░░▌   ▄▀▀▄░░▀░▄▀▄ ▐██▀▄
   ░███░  ▄▓▓▄▄░▀▀█▀█ ▌░░  ▀█▀█▀▀     ▐██▀
 █▀▄▐██   ▀░░   ▄▀ ▐ █    ▀ ▄▄▄░     ░▀▄█▄▀█
 ▌▄  █▓ ▒      ░  █▄█▄▀▄▄▄███▄▀▄ ░░   ░ ▀  █▌
  █▌▄░▌      ░░░▄▀█▀███████▄▀▄▀▄▀▀▄▄▄  █▀█░▐
   ██▄     ░░░▄█▄▀██▄█■██████▄█▄█▄■▀█░  ▐░▐
    ▀██░   ░▄██████████████████▄█▄█ ░█ ░ ▄▀
    ▀▓█▄▓░░  ▒█▀█████████████████████▒ ██▀
     ▀███ ▓▒   ██████████████▀▀▀▀█▄▀ ░▄█▒
      ▀███ ▀█▄▀▄█████▀▀  ▓▓▓▄░   ▐  ░▄██
        ▀██ ▄███████▄████████▀░░   ░▄██
  ▄██▀▀▄ █▄▀▄██▒▒███████████▀▀▀▄░ ░███░
▄██▀▄▄░░▀▐▄████▄ █████▀▄░░█▀▄▀░░  ▄██░
█████▄▄▄███▀░█▌██▄▀▀█████▄▄░░░▄▄███▀██▄ ▄▀▀▀▄▄
 ▀██████▀■▄█▄▄ ░▀███████████████▓▓░░▄██▀▄████▄▄▀▄

█▀█ █  █▀█ █▀█ █▄▀ ▐▀█▀▌█▀█ █▀█ █▄ █ ▀█▀ █▀█ █▀▀
█▀▄ █  █ █ █   █ ▀▄  █  █▀▄ █ █ █ ▀█  █  █   ▀▀█
█▄█ █▄▌█▄█ █▄█ █  █  █  █ █ █▄█ █  █ ▄█▄ █▄█ █▄█

THERE WILL BE BLOCKS               march 01 2017

@return

@see libc/str/str.h

@see kCp437i[]

@see libc/nexgen32e/kcp437.S

kCpuids

Globally precomputed CPUID.

This module lets us check CPUID in 0.06ns rather than 51.00ns. If every piece of native software linked this module, then the world would be a much better place; since all the alternatives are quite toilsome.

@return

@see www.felixcloutier.com/x86/cpuid

@see libc/nexgen32e/kcpuids.S

kCrashSigs

@type

int[8]

@see libc/log/oncrash.c

kDos2Errno

data structure for __dos2errno()

@return

@see libc/sysv/dos2errno.sh for the numbers

@see libc/intrin/kdos2errno.S

kHexToInt

@type

const char[256]

@see libc/str/khextoint.c

kHttpMethod

@type

const char[8][18]

@see net/http/khttpmethod.c

kHttpRepeatable

Set of standard comma-separate HTTP headers that may span lines.

These headers may specified on multiple lines, e.g.

Allow: GET
Allow: POST

Is the same as:

Allow: GET, POST

Standard headers that aren't part of this set will be overwritten in the event that they're specified multiple times. For example,

Content-Type: application/octet-stream
Content-Type: text/plain; charset=utf-8

Is the same as:

Content-Type: text/plain; charset=utf-8

This set exists to optimize header lookups and parsing. The existence of standard headers that aren't in this set is an O(1) operation. The repeatable headers in this list require an O(1) operation if they are not present, otherwise the extended headers list needs to be crawled.

Please note non-standard headers exist, e.g. Cookie, that may span multiple lines, even though they're not comma-delimited. For those headers we simply don't add them to the perfect hash table.

@type

_Bool[93]

@note we choose to not recognize this grammar for kHttpConnection

@note grep '[A-Z][a-z]*".*":"' rfc2616

@note grep ':.*#' rfc2616

@see RFC7230 § 4.2

@see net/http/khttprepeatable.c

kHttpToken

generated by: o//tool/build/xlat.com -TiC ' ()<>@,;:\"/[]?={}' -iskHttpToken

present            absent
────────────────   ────────────────
                   ∅☺☻♥♦♣♠•◘○◙♂♀♪♫☼   0x00
                   ►◄↕‼¶§▬↨↑↓→←∟↔▲▼   0x10
 ! #$%&‘  *+ -.    ␠ “     ()  ,  /   0x20
0123456789                   :;<=>⁇   0x30
 ABCDEFGHIJKLMNO   @                  0x40
PQRSTUVWXYZ   ^_              [⭝]     0x50
`abcdefghijklmno                      0x60
pqrstuvwxyz | ~               { } ⌂   0x70
                   ÇüéâäàåçêëèïîìÄÅ   0x80
                   ÉæÆôöòûùÿÖÜ¢£¥€ƒ   0x90
                   áíóúñÑªº¿⌐¬½¼¡«»   0xa0
                   ░▒▓│┤╡╢╖╕╣║╗╝╜╛┐   0xb0
                   └┴┬├─┼╞╟╚╔╩╦╠═╬╧   0xc0
                   ╨╤╥╙╘╒╓╫╪┘┌█▄▌▐▀   0xd0
                   αßΓπΣσμτΦΘΩδ∞φε∩   0xe0
                   ≡±≥≤⌠⌡÷≈°∙×√ⁿ²■λ   0xf0

const char kHttpToken[256] = { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 0x00 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 0x10 0, 1, 0, 1, 1, 1, 1, 1, 0, 0, 1, 1, 0, 1, 1, 0, // 0x20 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, // 0x30 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, // 0x40 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 1, 1, // 0x50 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, // 0x60 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 1, 0, 1, 0, // 0x70 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 0x80 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 0x90 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 0xa0 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 0xb0 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 0xc0 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 0xd0 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 0xe0 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 0xf0 };

@return

@see RFC2616 CHAR = <any US-ASCII character (octets 0 - 127)> SP = <US-ASCII SP, space (32)> HT = <US-ASCII HT, horizontal-tab (9)> CTL = <any US-ASCII control character

         (octets 0 - 31) and DEL (127)>

token = 1*<any CHAR except CTLs or separators> separators = "(" | ")" | "<" | ">" | "@"

       | "," | ";" | ":" | "\" | <">
       | "/" | "[" | "]" | "?" | "="
       | "{" | "}" | SP | HT

@see net/http/khttptoken.S

kill

Sends signal to process.

The impact of this action can be terminating the process, or interrupting it to request something happen.

@param

int pid: can be: >0 signals one process by id =0 signals all processes in current process group -1 signals all processes possible (except init) <-1 signals all processes in -pid process group
int sig: can be: >0 can be SIGINT, SIGTERM, SIGKILL, SIGUSR1, etc. =0 checks both if pid exists and we can signal it

@return

int: 0 if something was accomplished, or -1 w/ errno

@raise ESRCH if pid couldn't be found

@raise EPERM if lacked permission to signal process

@raise EPERM if pledge() is in play without proc promised

@raise EINVAL if the provided sig is invalid or unsupported

@asyncsignalsafe

@see libc/calls/kill.c

killpg

Sends signal to process group.

@param

int pgrp
int sig

@return

int

@see libc/calls/killpg.c

kisdangerous

@param

void* p

@return

_Bool

@see libc/intrin/kprintf.greg.c

kmalloc

Allocates permanent memory.

The code malloc() depends upon uses this function to allocate memory. The returned memory can't be freed, and leak detection is impossible. This function panics when memory isn't available.

Memory returned by this function is aligned on the word size, and as such, kmalloc() shouldn't be used for vector operations.

@param

unsigned long size

@return

void*: zero-initialized memory on success, or null w/ errno

@raise ENOMEM if we require more vespene gas

@see libc/intrin/kmalloc.c

kMbBittab

@type

const unsigned int[51]

@see libc/str/mb.c

kNtSystemDirectory

RII constant holding 'C:/WINDOWS/SYSTEM32' directory.

@return

@note guarantees trailing slash if non-empty

@see libc/calls/kntsystemdirectory.S

kNtWindowsDirectory

RII constant holding 'C:/WINDOWS' directory.

@return

@note guarantees trailing slash if non-empty

@see libc/calls/kntwindowsdirectory.S

kNtWsaData

Information about underlying Windows Sockets implementation.

Cosmopolitan automatically calls YOINK() on this symbol when its Berkeley Socket wrappers are linked. The latest version of Winsock was introduced alongside x64, so this should never fail.

@type

struct kNtWsaData

@see libc/sock/kntwsadata.c

kprintf

Privileged printf().

This function is intended for crash reporting. It's designed to be as unbreakable as possible, so that error messages can always be printed even when the rest of the runtime is broken. As such, it has continue on error semantics, doesn't support buffering between invocations and floating point is not supported. Output is also truncated if the line gets too long, but care is taken to preserve your newline characters. Your errno and GetLastError() state will not be clobbered, and ftrace and other runtime magic won't be invoked, since all the runtime magic depends on this function.

Directives:

%[FLAGS][WIDTH|*][.[PRECISION|*]][TYPE]SPECIFIER

Specifiers:

c char
o octal
b binary
s string
t symbol
p pointer
d decimal
n newline
u unsigned
r carriage
m strerror
G strsignal
X uppercase
T timestamp
x hexadecimal
P PID (or TID if TLS is enabled)

Types:

hhh bool
hh char or cp437
h short or char16_t
l long or wchar_t
ll long long

Flags:

0 zero padding
- flip alignment
! bypass memory safety
, thousands grouping w/ comma
' thousands grouping w/ apostrophe
_ thousands grouping w/ underscore
+ plus leftpad if positive (aligns w/ negatives)
space leftpad if positive (aligns w/ negatives)
# represent value with literal syntax, e.g. 0x, 0b, quotes
^ uppercasing w/ towupper() if linked, otherwise toupper()

Error numbers:

%m formats error (if strerror_wr if is linked)
%m formats errno number (if strerror_wr isn't linked)
% m formats error with leading space if errno isn't zero
%lm means favor WSAGetLastError() over GetLastError() if linked

You need to link and load the symbol table before %t will work. You can do that by calling GetSymbolTable(). If that hasn't happened it will print &hexnumber instead.

@param

const char* fmt
...

@return

void

@asyncsignalsafe

@vforksafe

@see libc/intrin/kprintf.greg.c

ksnprintf

Privileged snprintf().

@param

char* b: is buffer, and guaranteed a NUL-terminator if n>0
unsigned long n: is number of bytes available in buffer
const char* fmt
...

@return

unsigned long: length of output excluding NUL, which may exceed n

@see kprintf() for documentation

@asyncsignalsafe

@vforksafe

@see libc/intrin/kprintf.greg.c

kStartTsc

Timestamp of process start.

@type

unsigned long

@see libc/runtime/winmain.greg.h

@see libc/crt/crt.S

@see libc/intrin/kstarttsc.c

kTmpPath

RII constant holding temporary file directory.

The order of precedence is:

$TMPDIR/
GetTempPath()
/tmp/

This guarantees trailing slash. We also guarantee kTmpPath won't be longer than PATH_MAX / 2.

@type

char[1024]

@see libc/calls/ktmppath.c

kToLower

ASCII uppercase → lowercase translation tables.

char kToLower[256];

@return

@see kToUpper

@see libc/nexgen32e/ktolower.S

kToUpper

ASCII lowercase → uppercase translation tables.

char kToUpper[256];

@return

@see kToLower

@see libc/nexgen32e/ktoupper.S

kvappendf

Appends formatted string to buffer.

This is an alternative to vappendf() that uses the kprintf() formatting facility. This has some advantages in terms of performance, code size, and memory safety. There's also disadvantages, such as lack of floating-point directives.

@param

char** b
const char* f
struct __va_list* v

@return

long

@see kprintf()

@see libc/stdio/kvappendf.c

kvprintf

Privileged vprintf.

@param

const char* fmt
struct __va_list* v

@return

void

@see kprintf() for documentation

@asyncsignalsafe

@vforksafe

@see libc/intrin/kprintf.greg.c

kvsnprintf

Privileged vsnprintf().

@param

char* b: is buffer, and guaranteed a NUL-terminator if n>0
unsigned long n: is number of bytes available in buffer
const char* fmt
struct __va_list* v

@return

unsigned long: length of output excluding NUL, which may exceed n

@see kprintf() for documentation

@asyncsignalsafe

@vforksafe

@see libc/intrin/kprintf.greg.c

kX86GradeNames

@type

struct IdName[10]

@see libc/intrin/x86gradenames.c

kX86MarchNames

@type

struct IdName[23]

@see libc/intrin/x86marchnames.c

kXedChipFeatures

Mapping of enum XedChip -> bitset<enum XedIsaSet>.

See related APIs, e.g. xed_isa_set_is_valid_for_chip().

This information can be reproduced by building Xed and running the C preprocessor on xed-chip-features-table.c (see xed-chips.txt) which turns several thousand lines of non-evolving code into fifty. For example, 0x2800000ul was calculated as: 1UL<<(XED_ISA_SET_I86-64) | 1UL<<(XED_ISA_SET_LAHF-64).

@type

const unsigned long[3][53]

@see third_party/xed/x86features.c

kXedEamode

@type

const unsigned char[3][2]

@see third_party/xed/eamode.c

kXedErrorNames

Xed error code names.

puts(IndexDoubleNulString(kXedErrorNames, xedd->op.error));

@type

const char[338]

@see XedError

@see third_party/xed/xederror.c

l64a

Converts 32-bit integer to base64, the posix way.

@param

long x

@return

char*

@see a64l() for inverse

@see EncodeBase64()

@see libc/str/l64a.c

labs

Returns absolute value of long integer.

@param

long x

@return

long

@note labs(LONG_MIN) returns LONG_MIN unless -ftrapv

@note consider ABS() to avoid narrowing

@see libc/fmt/labs.c

landlock_add_rule

Adds new rule to Landlock ruleset.

@param

int fd
enum rule_type rule_type
void* rule_attr
unsigned int flags

@return

int

@error ENOSYS if Landlock isn't supported

@error EPERM if Landlock supported but SECCOMP BPF shut it down

@error EOPNOTSUPP if Landlock supported but disabled at boot time

@error EINVAL if flags not 0, or inconsistent access in the rule, i.e. landlock_path_beneath_attr::allowed_access is not a subset of the ruleset handled accesses

@error ENOMSG empty allowed_access

@error EBADF fd is not a file descriptor for current thread, or member of rule_attr is not a file descriptor as expected

@error EBADFD fd is not a ruleset file descriptor, or a member of rule_attr is not the expected file descriptor type

@error EPERM fd has no write access to the underlying ruleset

@error EFAULT rule_attr inconsistency

@see libc/calls/landlock_add_rule.c

landlock_create_ruleset

Create new Landlock filesystem sandboxing ruleset.

You may also use this function to query the current ABI version:

landlock_create_ruleset(0, 0, LANDLOCK_CREATE_RULESET_VERSION);

@param

struct landlock_ruleset_attr* attr
unsigned long size
unsigned int flags

@return

int: close exec file descriptor for new ruleset

@error ENOSYS if not running Linux 5.13+

@error EPERM if pledge() or seccomp bpf shut it down

@error EOPNOTSUPP Landlock supported but disabled at boot

@error EINVAL unknown flags, or unknown access, or too small size

@error E2BIG attr or size inconsistencies

@error EFAULT attr or size inconsistencies

@error ENOMSG empty landlock_ruleset_attr::handled_access_fs

@see libc/calls/landlock_create_ruleset.c

landlock_restrict_self

Enforces Landlock ruleset on calling thread.

@param

int fd
unsigned int flags

@return

int

@error EOPNOTSUPP if Landlock supported but disabled at boot time

@error EINVAL if flags isn't zero

@error EBADF if fd isn't file descriptor for the current thread

@error EBADFD if fd is not a ruleset file descriptor

@error EPERM if fd has no read access to underlying ruleset, or current thread is not running with no_new_privs, or it doesn’t have CAP_SYS_ADMIN in its namespace

@error E2BIG if the maximum number of stacked rulesets is reached for current thread

@see libc/calls/landlock_restrict_self.c

lchmod

Changes mode of pathname, w/o dereferencing symlinks.

@param

const char* pathname
unsigned int mode

@return

int: 0 on success, or -1 w/ errno

@see chown() which dereferences symbolic links

@see /etc/passwd for user ids

@see /etc/group for group ids

@see libc/calls/lchmod.c

lchown

Changes owner and/or group of pathname, w/o dereferencing symlinks.

@param

const char* pathname
unsigned int uid: is user id, or -1u to not change
unsigned int gid: is group id, or -1u to not change

@return

int: 0 on success, or -1 w/ errno

@see chown() which dereferences symbolic links

@see /etc/passwd for user ids

@see /etc/group for group ids

@see libc/calls/lchown.c

lcong48

@param

unsigned short* p

@return

void

@see third_party/musl/rand48.c

ldexp

Returns 𝑥 × 2ʸ.

@param

double x
int n

@return

double

@see libc/tinymath/ldexp.c

ldexpf

Returns 𝑥 × 2ʸ.

@param

float x
int n

@return

float

@see libc/tinymath/ldexpf.c

ldexpl

Returns 𝑥 × 2ʸ.

@param

𝑥: is long double passed on stack
𝑦: is exponent via %edi

@return

: result in %st0

@see libc/tinymath/ldexpl.S

ldiv

@param

long num
long den

@return

struct ldiv_t

@see libc/fmt/ldiv.c

LeftmostInt

@param

struct SortedInts* t
int k

@return

int

@see libc/mem/sortedints.c

LengthInt64

Returns len(str(x)) where x is a signed 64-bit integer.

@param

long x

@return

unsigned int

@see libc/intrin/lengthuint64.c

LengthInt64Thousands

Returns decimal string length of int64 w/ thousands separators.

@param

long x

@return

unsigned int

@see libc/intrin/lengthuint64.c

LengthUint64

Returns len(str(x)) where x is an unsigned 64-bit integer.

@param

unsigned long x

@return

unsigned int

@see libc/intrin/lengthuint64.c

LengthUint64Thousands

Returns decimal string length of uint64 w/ thousands separators.

@param

unsigned long x

@return

unsigned int

@see libc/intrin/lengthuint64.c

lgamma

Returns natural logarithm of absolute value of gamma function.

@param

double x

@return

double

@see libc/tinymath/lgamma.c

lgamma_r

@param

double x
int* signgamp

@return

double

@see libc/tinymath/gamma.c

lgammaf

@param

float x

@return

float

@see libc/tinymath/lgammaf.c

lgammaf_r

Returns natural logarithm of absolute value of Gamma function.

@param

float x
int* signgamp

@return

float

@see libc/tinymath/lgammaf_r.c

link

Creates hard filesystem link.

This allows two names to point to the same file data on disk. They can only be differentiated by examining the inode number.

@param

const char* existingpath
const char* newpath

@return

int: 0 on success, or -1 w/ errno

@asyncsignalsafe

@see libc/calls/link.c

linkat

Creates hard filesystem link.

This allows two names to point to the same file data on disk. They can only be differentiated by examining the inode number.

@param

int olddirfd
const char* oldpath
int newdirfd
const char* newpath
int flags: can have AT_EMPTY_PATH or AT_SYMLINK_NOFOLLOW

@return

int: 0 on success, or -1 w/ errno

@asyncsignalsafe

@see libc/calls/linkat.c

listen

Asks system to accept incoming connections on socket.

The socket() and bind() functions need to be called beforehand. Once this function is called, accept() is used to wait for connections. Using this on connectionless sockets will allow it to receive packets on a designated address.

@param

int fd
int backlog: <= SOMAXCONN

@return

int: 0 on success or -1 w/ errno

@see libc/sock/listen.c

llabs

Returns absolute value of long long integer.

@param

long x

@return

long

@note llabs(LONG_LONG_MIN) returns LONG_LONG_MIN unless -ftrapv

@note consider ABS() to avoid narrowing

@see libc/fmt/llabs.c

lldiv

@param

long num
long den

@return

struct lldiv_t

@see libc/fmt/lldiv.c

llround

Rounds to nearest integer, away from zero.

@param

𝑥: is double scalar in low half of %xmm0

@return

: 64-bit signed integer in %rax

@see round(), lrint()

@see libc/tinymath/lround.S

llroundf

Rounds to nearest integer, away from zero.

@param

𝑥: is float scalar in low quarter of %xmm0

@return

: 64-bit signed integer in %rax

@see round()

@see libc/tinymath/lroundf.S

_loadxmm

Loads XMM registers from buffer.

@param

%rdi: points to &(forcealign(16) uint8_t[256])[128]

@return

@note modern cpus have out-of-order execution engines

@see libc/nexgen32e/loadxmm.S

localeconv

@return

struct lconv*

@see libc/str/localeconv.c

localtime

@param

const long* timep

@return

struct alttm*

@see libc/time/localtime.c

localtime_funlock

@return

void

@see libc/time/localtime.c

localtime_lock

@return

void

@see libc/time/localtime.c

localtime_r

@param

const long* timep
struct alttm* tmp

@return

struct alttm*

@see libc/time/localtime.c

localtime_unlock

@return

void

@see libc/time/localtime.c

lockf

Locks file.

@param

int fd
int op
long size

@return

int

@cancellationpoint when op is F_LOCK

@see third_party/musl/lockf.c

LockFileEx

Locks file on the New Technology.

@param

long hFile
unsigned int dwFlags
unsigned int dwReserved
unsigned int nNumberOfBytesToLockLow
unsigned int nNumberOfBytesToLockHigh
struct inout_lpOverlapped* lpOverlapped

@return

int: handle, or -1 on failure

@note this wrapper takes care of ABI, STRACE(), and __winerr()

@see libc/intrin/lockfileex.c

log

Returns natural logarithm of 𝑥.

@param

𝑥: is double scalar in low half of %xmm0

@return

: double scalar in low half of %xmm0

@see libc/tinymath/log-tiny.S

log10

Calculates log₁₀𝑥.

@param

𝑥: is double scalar in low half of %xmm0

@return

: double scalar in low half of %xmm0

@see libc/tinymath/log10-tiny.S

log10f

Calculates log₁₀𝑥.

@param

𝑥: is double scalar in low quarter of %xmm0

@return

: float scalar in low quarter of %xmm0

@see libc/tinymath/log10f.S

log10l

Calculates log₁₀𝑥.

@param

𝑥: is an 80-bit long double passed on stack in 16-bytes

@return

: result in %st

@see libc/tinymath/log10l.S

log1p

Returns log(𝟷+𝑥).

@param

𝑥: is double scalar in low half of %xmm0

@return

: double scalar in low half of %xmm0

@see libc/tinymath/log1p-tiny.S

log1pf

Returns log(𝟷+𝑥).

@param

𝑥: is float scalar in low quarter of %xmm0

@return

: float scalar in low quarter of %xmm0

@see libc/tinymath/log1pf.S

log1pl

Returns log(𝟷+𝑥).

@param

𝑥: is an 80-bit long double passed on stack in 16-bytes

@return

: result of exponentiation on FPU stack in %st

@see libc/tinymath/log1pl.S

log2

Calculates log₂𝑥.

@param

𝑥: is a double passed in the lower quadword of %xmm0

@return

: result in lower quadword of %xmm0

@see libc/tinymath/log2-tiny.S

log2f

Calculates log₂𝑥.

@param

𝑥: is a float passed in the lower quarter of %xmm0

@return

: result in lower quarter of %xmm0

@see libc/tinymath/log2f-tiny.S

log2l

Calculates log₂𝑥.

@param

𝑥: is an 80-bit long double passed on stack in 16-bytes

@return

: result in %st

@see ilogbl()

@see libc/tinymath/log2l.S

__log_file

Log level for compile-time DCE.

@type

struct FILE*

@see libc/log/log.h

logb

Returns log₂ₓ exponent part of double.

@param

𝑥: is double passed in %xmm0

@return

: result in %xmm0

@see libc/tinymath/logb.S

logbf

Returns log₂ₓ exponent part of float.

@param

𝑥: is float passed in %xmm0

@return

: result in %xmm0

@see libc/tinymath/logbf.S

logbl

Returns log₂ₓ exponent part of long double.

@param

𝑥: is long double passed on stack

@return

: result in %st0

@see libc/tinymath/logbl.S

logf

Returns natural logarithm of 𝑥.

@param

𝑥: is double scalar in low quarter of %xmm0

@return

: float scalar in low quarter of %xmm0

@see libc/tinymath/logf.S

login_tty

Prepares terminal for login.

@param

int fd

@return

int: 0 on success, or -1 w/ errno

@raise ENOSYS on Windows and Metal

@raise EPERM if terminal is already controlling another sid

@see libc/runtime/login_tty.c

logl

Returns natural logarithm of 𝑥.

@param

𝑥: is an 80-bit long double passed on stack in 16-bytes

@return

: result on FPU stack in %st

@see libc/tinymath/logl.S

longerjmp

Loads previously saved processor state.

@param

rdi: points to the jmp_buf
rsi: is returned by setlongerjmp() invocation

@noreturn

@see libc/nexgen32e/longerjmp.S

_longjmp

Loads previously saved processor state.

@param

rdi: points to the jmp_buf
esi: is returned by setjmp() invocation (coerced nonzero)

@noreturn

@see _gclongjmp()

@see siglongjmp()

@see libc/nexgen32e/longjmp.S

longjmp

Loads previously saved processor state.

@param

rdi: points to the jmp_buf
esi: is returned by setjmp() invocation (coerced nonzero)

@noreturn

@see _gclongjmp()

@see siglongjmp()

@see libc/nexgen32e/longjmp.S

_longsort

Sorting algorithm for longs that doesn't take long.

"What disorder is this? Give me my long sort!"
                          -Lord Capulet

@param

long* A
unsigned long n

@return

void

@see libc/str/longsort.c

LookupProtoByName

Opens and searches /etc/protocols to find number for a given name.

@param

const char* protoname

is a NULL-terminated string

char* buf

is a buffer to store the official name of the protocol

unsigned long bufsize

is the size of buf

const char* filepath

is the location of protocols file

 (if NULL, uses /etc/protocols)

@return

int

-1 on error, or

 positive protocol number

@note aliases are read from file for comparison, but not returned.

@see LookupProtoByNumber

@see libc/dns/lookupprotobyname.c

LookupProtoByNumber

Opens and searches /etc/protocols to find name for a given number.

The format of /etc/protocols is like this:

# comment
# NAME           PROTOCOL        ALIASES
ip               0               IP
icmp             1               ICMP

@param

const int protonum

is the protocol number

char* buf

is a buffer to store the official name of the protocol

unsigned long bufsize

is the size of buf

const char* filepath

is the location of the protocols file

 (if NULL, uses /etc/protocols)

@return

int: 0 on success, -1 on error

@note aliases are not read from the file.

@see libc/dns/lookupprotobynumber.c

LookupServicesByName

Opens and searches /etc/services to find port for a given name.

@param

const char* servname

is a NULL-terminated string

char* servproto

is a NULL-terminated string (eg "tcp", "udp")

 (if servproto is an empty string,
  if is filled with the first matching
  protocol)

unsigned long servprotolen

the size of servproto

char* buf

is a buffer to store the official name of the service

 (if NULL, the official name is not stored)

unsigned long bufsize

is the size of buf

const char* filepath

is the location of services file

 (if NULL, uses /etc/services)

@return

int: -1 on error, or positive port number

@note aliases are read from file for comparison, but not returned.

@see LookupServicesByPort

@threadsafe

@see libc/dns/lookupservicesbyname.c

LookupServicesByPort

Opens and searches /etc/services to find name for a given port.

The format of /etc/services is like this:

# comment
# NAME       PORT/PROTOCOL       ALIASES
ftp          21/tcp
fsp          21/udp              fspd
ssh          22/tcp

@param

const int servport

is the port number

char* servproto

is a NULL-terminated string (eg "tcp", "udp")

 (if servproto is an empty string,
  if is filled with the first matching
  protocol)

unsigned long servprotolen

the size of servproto

char* buf

is a buffer to store the official name of the service

unsigned long bufsize

is the size of buf

const char* filepath

is the location of the services file

 (if NULL, uses /etc/services)

@return

int: 0 on success, -1 on error

@note aliases are not read from the file.

@see libc/dns/lookupservicesbyport.c

lrand48

@return

long

@see third_party/musl/rand48.c

lround

Rounds to nearest integer, away from zero.

@param

𝑥: is double scalar in low half of %xmm0

@return

: 64-bit signed integer in %rax

@see round(), lrint()

@see libc/tinymath/lround.S

lroundf

Rounds to nearest integer, away from zero.

@param

𝑥: is float scalar in low quarter of %xmm0

@return

: 64-bit signed integer in %rax

@see round()

@see libc/tinymath/lroundf.S

lseek

Changes current position of file descriptor, e.g.

int fd = open("hello.bin", O_RDONLY);
lseek(fd, 100, SEEK_SET);  // set position to 100th byte
read(fd, buf, 8);          // read bytes 100 through 107

This function may be used to inspect the current position:

int64_t pos = lseek(fd, 0, SEEK_CUR);

You may seek past the end of file. If a write happens afterwards then the gap leading up to it will be filled with zeroes. Please note that lseek() by itself will not extend the physical medium.

If dup() is used then the current position will be shared across multiple file descriptors. If you seek in one it will implicitly seek the other too.

The current position of a file descriptor is shared between both processes and threads. For example, if an fd is inherited across fork(), and both the child and parent want to read from it, then changes made by one are observable to the other.

The pread() and pwrite() functions obfuscate the need for having global shared file position state. Consider using them, since it helps avoid the gotchas of this interface described above.

This function is supported by all OSes within our support vector and our unit tests demonstrate the behaviors described above are consistent across platforms.

@param

int fd

is a number returned by open()

long offset

is 0-indexed byte count w.r.t. whence

int whence

can be one of:

SEEK_SET: Sets the file position to offset [default]
SEEK_CUR: Sets the file position to position + offset
SEEK_END: Sets the file position to filesize + offset

@return

long: new position relative to beginning, or -1 w/ errno

@raise ESPIPE if fd is a pipe, socket, or fifo

@raise EBADF if fd isn't an open file descriptor

@raise EINVAL if resulting offset would be negative

@raise EINVAL if whence isn't valid

@asyncsignalsafe

@threadsafe

@vforksafe

@see libc/calls/lseek.c

lstat

Returns information about file, w/o traversing symlinks.

@param

const char* pathname
struct stat* st

@return

int

@asyncsignalsafe

@see libc/calls/lstat.c

lutimes

Changes file timestamps, the legacy way.

@param

const char* filename
ANONYMOUS-STRUCT* tv

@return

int

@see libc/calls/lutimes.c

lz4check

@param

void* data

@return

const unsigned char*

@see libc/str/lz4check.c

lz4cpy

Decompresses LZ4 block.

This is a 103 byte implementation of the LZ4 algorithm. Please note LZ4 files are comprised of multiple frames, which may be decoded together using the wrapper function lz4decode().

@param

void* dest
void* blockdata
unsigned long blocksize

@return

void*

@see rldecode() for a 16-byte decompressor

@see libc/str/lz4cpy.c

lz4decode

Decompresses LZ4 file.

We assume (1) the file is mmap()'d or was copied into into memory beforehand; and (2) folks handling untrustworthy data shall place 64kb of guard pages on the ends of each buffer, see mapanon(). We don't intend to support XXHASH; we recommend folks needing checks against data corruption consider crc32c(), or gzip since it's the best at file recovery. Dictionaries are supported; by convention, they are passed in the ≤64kb bytes preceding src.

@param

void* dest
void* src

@return

void*: pointer to end of decoded data, similar to mempcpy()

@see _mapanon(), lz4check()

@see libc/str/lz4decode.c

madvise

Drops hints to O/S about intended access patterns of mmap()'d memory.

@param

void* addr
unsigned long length
int advice: can be MADV_WILLNEED, MADV_SEQUENTIAL, MADV_FREE, etc.

@return

int: 0 on success, or -1 w/ errno

@see libc/sysv/consts.sh

@see fadvise()

@see libc/calls/madvise.c

major

@param

unsigned long x

@return

unsigned int

@see libc/calls/major.c

makedev

@param

unsigned int x
unsigned int y

@return

unsigned long

@see libc/calls/makedev.c

makedirs

Creates directory and parent components.

This function is similar to mkdir() except it iteratively creates parent directories and it won't fail if the directory already exists.

@param

const char* path: is a UTF-8 string, preferably relative w/ forward slashes
unsigned int mode: can be, for example, 0755

@return

int: 0 on success or -1 w/ errno

@raise EEXIST if named file already exists as non-directory

@raise ENOTDIR if directory component in path existed as non-directory

@raise ENAMETOOLONG if symlink-resolved path length exceeds PATH_MAX

@raise ENAMETOOLONG if component in path exists longer than NAME_MAX

@raise EROFS if parent directory is on read-only filesystem

@raise ENOSPC if file system or parent directory is full

@raise EACCES if write permission was denied on parent directory

@raise EACCES if search permission was denied on component in path

@raise ENOENT if path is an empty string

@raise ELOOP if loop was detected resolving components of path

@asyncsignalsafe

@threadsafe

@see libc/calls/makedirs.c

mallinfo

@param

struct mallinfo*

@return

struct mallinfo

@see libc/mem/mallinfo.c

malloc

Allocates uninitialized memory.

Returns a pointer to a newly allocated chunk of at least n bytes, or null if no space is available, in which case errno is set to ENOMEM on ANSI C systems.

If n is zero, malloc returns a minimum-sized chunk. (The minimum size is 32 bytes on 64bit systems.) Note that size_t is an unsigned type, so calls with arguments that would be negative if signed are interpreted as requests for huge amounts of space, which will often fail. The maximum supported value of n differs across systems, but is in all cases less than the maximum representable value of a size_t.

@param

rdi: is number of bytes needed, coerced to 1+

@return

: new memory, or NULL w/ errno

@threadsafe

@see libc/mem/malloc.S

malloc_inspect_all

@param

void(*)() handler
void* arg

@return

void

@see libc/mem/malloc_inspect_all.c

malloc_trim

Releases freed memory back to system.

@param

rdi: specifies bytes of memory to leave available

@return

: 1 if it actually released any memory, else 0

@see libc/mem/malloc_trim.S

malloc_usable_size

Returns the number of bytes you can actually use in an allocated chunk, which may be more than you requested (although often not) due to alignment and minimum size constraints.

You can use this many bytes without worrying about overwriting other allocated objects. This is not a particularly great programming practice. malloc_usable_size can be more useful in debugging and assertions, for example:

p = malloc(n)
assert(malloc_usable_size(p) >= 256)

@param

rdi: is address of allocation

@return

: rax is total number of bytes

@see dlmalloc_usable_size()

@threadsafe

@see libc/mem/malloc_usable_size.S

__map_phdrs

Maps APE-defined ELF program headers into memory and clears BSS.

@param

struct mman* mm
unsigned long* pml4t
unsigned long b
unsigned long top

@return

void

@see libc/intrin/mman.greg.c

_mapanon

Helper function for allocating anonymous mapping.

This function is equivalent to:

mmap(NULL, mapsize, PROT_READ | PROT_WRITE,
     MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);

If mmap() fails, possibly because the parent process did this:

if (!vfork()) {
  setrlimit(RLIMIT_AS, &(struct rlimit){maxbytes, maxbytes});
  execv(prog, (char *const[]){prog, 0});
}
wait(0);

Then this function will call:

__oom_hook(size);

If it's linked. The LIBC_TESTLIB library provides an implementation, which can be installed as follows:

int main() {
    InstallQuotaHandlers();
    // ...
}

That is performed automatically for unit test executables.

@param

unsigned long size

@return

void*: memory map address on success, or null w/ errno

@see libc/runtime/mapanon.c

_mapshared

Creates anonymous shared memory mapping.

@param

unsigned long size

@return

void*: memory map address on success, or null w/ errno

@see libc/runtime/mapshared.c

_mapstack

Allocates stack.

The size of your returned stack is always GetStackSize().

The bottom 4096 bytes of your stack can't be used, since it's always reserved for a read-only guard page. With ASAN it'll be poisoned too.

The top 16 bytes of a stack can't be used due to openbsd:stackbound and those bytes are also poisoned under ASAN build modes.

@return

void*: stack bottom address on success, or null w/ errno

@see libc/runtime/mapstack.c

MapViewOfFileEx

Maps view of file mapping into memory on the New Technology.

@param

long hFileMappingObject: was returned by CreateFileMapping()
unsigned int dwDesiredAccess: has kNtFileMap... flags
unsigned int dwFileOffsetHigh
unsigned int dwFileOffsetLow
unsigned long dwNumberOfBytesToMap
void* opt_lpDesiredBaseAddress: may be NULL to let o/s choose

@return

void*: base address, or NULL on failure

@note this wrapper takes care of ABI, STRACE(), and __winerr()

@see libc/intrin/mapviewoffileex.c

MapViewOfFileExNuma

Maps view of file mapping into memory on the New Technology.

@param

long hFileMappingObject: was returned by CreateFileMapping()
unsigned int dwDesiredAccess: has kNtFileMap... flags
unsigned int dwFileOffsetHigh
unsigned int dwFileOffsetLow
unsigned long dwNumberOfBytesToMap
void* opt_lpDesiredBaseAddress: may be NULL to let o/s choose
unsigned int nndDesiredNumaNode

@return

void*: base address, or NULL on failure

@note this wrapper takes care of ABI, STRACE(), and __winerr()

@see libc/intrin/mapviewoffileexnuma.c

MarsagliaXorshift32

@param

unsigned int* state

@return

unsigned int

@see libc/stdio/xorshift32.c

MarsagliaXorshift64

@param

unsigned long* state

@return

unsigned long

@see libc/stdio/xorshift64.c

mblen

@param

const char* s
unsigned long n

@return

int

@see libc/str/mblen.c

mbrlen

@param

const char* s
unsigned long n
unsigned int* t

@return

unsigned long

@see libc/str/mbrlen.c

mbrtoc16

@param

unsigned short* pc16
const char* s
unsigned long n
unsigned int* ps

@return

unsigned long

@see libc/str/mbrtoc16.c

mbrtoc32

@param

unsigned int* pc32
const char* s
unsigned long n
unsigned int* ps

@return

unsigned long

@see libc/str/mbrtoc32.c

mbrtowc

@param

int* wc
const char* src
unsigned long n
unsigned int* st

@return

unsigned long

@see libc/str/mbrtowc.c

mbsinit

@param

const unsigned int* t

@return

int

@see libc/str/mbsinit.c

mbsnrtowcs

@param

int* wcs
const char** src
unsigned long n
unsigned long wn
unsigned int* st

@return

unsigned long

@see libc/str/mbsnrtowcs.c

mbsrtowcs

@param

int* ws
const char** src
unsigned long wn
unsigned int* st

@return

unsigned long

@see libc/str/mbsrtowcs.c

mbstowcs

@param

int* pwc
const char* s
unsigned long wn

@return

unsigned long

@see libc/str/mbstowcs.c

mbtowc

@param

int* wc
const char* src
unsigned long n

@return

int

@see libc/str/mbtowc.c

MeasureEntropy

Returns Shannon entropy of array.

This gives you an idea of the density of information. Cryptographic random should be in the ballpark of 7.9 whereas plaintext will be more like 4.5.

@param

const char* p: is treated as binary octets
unsigned long n: should be at least 1000

@return

double: number between 0 and 8

@see libc/tinymath/measureentropy.c

memalign

Allocates aligned memory.

Returns a pointer to a newly allocated chunk of n bytes, aligned in accord with the alignment argument. The alignment argument shall be rounded up to the nearest two power and higher 2 powers may be used if the allocator imposes a minimum alignment requirement.

@param

rdi: is alignment in bytes, coerced to 1+ w/ 2-power roundup
rsi: is number of bytes needed, coerced to 1+

@return

: rax is memory address, or NULL w/ errno

@see valloc(), pvalloc()

@threadsafe

@see libc/mem/memalign.S

memcasecmp

Compares memory case-insensitively.

memcasecmp n=0                     992 picoseconds
memcasecmp n=1                       1 ns/byte            590 mb/s
memcasecmp n=2                       1 ns/byte            843 mb/s
memcasecmp n=3                       1 ns/byte            885 mb/s
memcasecmp n=4                       1 ns/byte            843 mb/s
memcasecmp n=5                       1 ns/byte            820 mb/s
memcasecmp n=6                       1 ns/byte            770 mb/s
memcasecmp n=7                       1 ns/byte            765 mb/s
memcasecmp n=8                     206 ps/byte          4,724 mb/s
memcasecmp n=9                     220 ps/byte          4,428 mb/s
memcasecmp n=15                    617 ps/byte          1,581 mb/s
memcasecmp n=16                    124 ps/byte          7,873 mb/s
memcasecmp n=17                    155 ps/byte          6,274 mb/s
memcasecmp n=31                    341 ps/byte          2,860 mb/s
memcasecmp n=32                     82 ps/byte         11,810 mb/s
memcasecmp n=33                    100 ps/byte          9,743 mb/s
memcasecmp n=80                     53 ps/byte         18,169 mb/s
memcasecmp n=128                    49 ps/byte         19,890 mb/s
memcasecmp n=256                    45 ps/byte         21,595 mb/s
memcasecmp n=16384                  42 ps/byte         22,721 mb/s
memcasecmp n=32768                  40 ps/byte         24,266 mb/s
memcasecmp n=131072                 40 ps/byte         24,337 mb/s

@param

void* p
void* q
unsigned long n

@return

int: is <0, 0, or >0 based on uint8_t comparison

@see libc/str/memcasecmp.c

memccpy

Copies at most N bytes from SRC to DST until 𝑐 is encountered.

This is little-known C Standard Library approach, dating back to the Fourth Edition of System Five, for copying a C strings to fixed-width buffers, with added generality.

For example, strictly:

char buf[16];
CHECK_NOTNULL(memccpy(buf, s, '\0', sizeof(buf)));

Or unstrictly:

if (!memccpy(buf, s, '\0', sizeof(buf))) strcpy(buf, "?");

Are usually more sensible than the following:

char cstrbuf[16];
snprintf(cstrbuf, sizeof(cstrbuf), "%s", CSTR);

@param

void* dst
void* src
int c: is search character and is masked with 255
unsigned long n

@return

void*: DST + idx(c) + 1, or NULL if 𝑐 ∉ 𝑠₀․․ₙ₋₁

@note DST and SRC can't overlap

@asyncsignalsafe

@see libc/str/memccpy.c

memchr16

Returns pointer to first instance of character in range.

@param

rdi: is a non-null pointer to memory
esi: is the search word
rdx: is length of memory in shorts

@return

: rax points to word if found or NULL

@asyncsignalsafe

@see libc/nexgen32e/strsak16.S

memfd_create

Creates anonymous file.

@param

const char* name: is used for the /proc/self/fd/FD symlink
unsigned int flags: can have MFD_CLOEXEC, MFD_ALLOW_SEALING

@return

int

@raise ENOSYS if not RHEL8+

@see libc/calls/memfd_create.c

memfrob

Memfrob implements a crypto algorithm proven to be unbreakable, without meeting its requirements concerning secrecy or length.

@param

void* buf
unsigned long size

@return

void*

@see libc/str/memfrob.c

_meminfo

Prints memory mappings.

@param

int fd

@return

void

@see libc/log/meminfo.c

memjmpinit

Initializes jump table for memset() and memcpy().

@param

!ZF: if required cpu vector extensions are available
rdi: is address of 64-bit jump table
rsi: is address of 8-bit jump initializers
rdx: is address of indirect branch
ecx: is size of jump table

@return

@see libc/nexgen32e/memjmpinit.S

memmove

Copies memory.

memmove n=0                        661 picoseconds
memmove n=1                        661 ps/byte          1,476 mb/s
memmove n=2                        330 ps/byte          2,952 mb/s
memmove n=3                        330 ps/byte          2,952 mb/s
memmove n=4                        165 ps/byte          5,904 mb/s
memmove n=7                        141 ps/byte          6,888 mb/s
memmove n=8                         82 ps/byte             11 GB/s
memmove n=15                        44 ps/byte             21 GB/s
memmove n=16                        41 ps/byte             23 GB/s
memmove n=31                        32 ps/byte             29 GB/s
memmove n=32                        31 ps/byte             30 GB/s
memmove n=63                        21 ps/byte             45 GB/s
memmove n=64                        15 ps/byte             61 GB/s
memmove n=127                       13 ps/byte             73 GB/s
memmove n=128                       31 ps/byte             30 GB/s
memmove n=255                       20 ps/byte             45 GB/s
memmove n=256                       19 ps/byte             49 GB/s
memmove n=511                       16 ps/byte             56 GB/s
memmove n=512                       17 ps/byte             54 GB/s
memmove n=1023                      18 ps/byte             52 GB/s
memmove n=1024                      13 ps/byte             72 GB/s
memmove n=2047                       9 ps/byte             96 GB/s
memmove n=2048                       9 ps/byte             98 GB/s
memmove n=4095                       8 ps/byte            112 GB/s
memmove n=4096                       8 ps/byte            109 GB/s
memmove n=8191                       7 ps/byte            124 GB/s
memmove n=8192                       7 ps/byte            125 GB/s
memmove n=16383                      7 ps/byte            134 GB/s
memmove n=16384                      7 ps/byte            134 GB/s
memmove n=32767                     13 ps/byte             72 GB/s
memmove n=32768                     13 ps/byte             72 GB/s
memmove n=65535                     13 ps/byte             68 GB/s
memmove n=65536                     14 ps/byte             67 GB/s
memmove n=131071                    14 ps/byte             65 GB/s
memmove n=131072                    14 ps/byte             64 GB/s
memmove n=262143                    15 ps/byte             63 GB/s
memmove n=262144                    15 ps/byte             63 GB/s
memmove n=524287                    15 ps/byte             61 GB/s
memmove n=524288                    15 ps/byte             61 GB/s
memmove n=1048575                   15 ps/byte             61 GB/s
memmove n=1048576                   15 ps/byte             61 GB/s
memmove n=2097151                   19 ps/byte             48 GB/s
memmove n=2097152                   27 ps/byte             35 GB/s
memmove n=4194303                   28 ps/byte             33 GB/s
memmove n=4194304                   28 ps/byte             33 GB/s
memmove n=8388607                   28 ps/byte             33 GB/s
memmove n=8388608                   28 ps/byte             33 GB/s

DST and SRC may overlap.

@param

void* dst: is destination
void* src: is memory to copy
unsigned long n: is number of bytes to copy

@return

void*: dst

@asyncsignalsafe

@see libc/intrin/memmove.c

mempcpy

@param

void* dst
void* src
unsigned long n

@return

void*

@see libc/intrin/mempcpy.c

memset16

Sets wide memory.

@param

unsigned short* p
unsigned short c
unsigned long n

@return

unsigned short*

@asyncsignalsafe

@see libc/str/memset16.c

mergesort

Sorts array.

@param

void* base
unsigned long nmemb: is item count
unsigned long size: is item width
int(*)() cmp: is a callback returning <0, 0, or >0

@return

int

@see mergesort_r()

@see heapsort()

@see qsort()

@see libc/mem/mergesort.c

mergesort_r

Sorts array w/ optional callback argument.

@param

void* base: is base of array
unsigned long nmemb: is item count
unsigned long size: is item width
int(*)() cmp: is a callback returning <0, 0, or >0
void* z: will optionally be passed as the third argument to cmp

@return

int

@see mergesort()

@see libc/mem/mergesort.c

MetalPrintf

Prints string to serial port.

This only supports %d and %s. It'll will work even if .rodata hasn't been loaded into memory yet.

@param

const char* fmt
...

@return

void

@see libc/runtime/metalprintf.greg.c

mincore

Tells you which pages are resident in memory.

@param

void* addr
unsigned long length
unsigned char* vec

@return

int

@see libc/calls/mincore.c

minor

@param

unsigned long x

@return

unsigned int

@see libc/calls/minor.c

mkdir

Creates directory a.k.a. folder.

mkdir o               →  0
mkdir o/yo/yo/yo      → -1 w/ ENOENT
if o/yo is file       → -1 w/ ENOTDIR
if o/yo/yo/yo is dir  → -1 w/ EEXIST
if o/yo/yo/yo is file → -1 w/ EEXIST

@param

const char* path: is a UTF-8 string, preferably relative w/ forward slashes
unsigned int mode: can be, for example, 0755

@return

int: 0 on success or -1 w/ errno

@raise EEXIST if named file already exists

@raise ENOTDIR if directory component in path existed as non-directory

@raise ENAMETOOLONG if symlink-resolved path length exceeds PATH_MAX

@raise ENAMETOOLONG if component in path exists longer than NAME_MAX

@raise EROFS if parent directory is on read-only filesystem

@raise ENOSPC if file system or parent directory is full

@raise EACCES if write permission was denied on parent directory

@raise EACCES if search permission was denied on component in path

@raise ENOENT if a component within path didn't exist

@raise ENOENT if path is an empty string

@raise ELOOP if loop was detected resolving components of path

@see makedirs() which is higher-level

@see mkdirat() for modern call

@asyncsignalsafe

@threadsafe

@see libc/calls/mkdir.c

mkdirat

Creates directory a.k.a. folder.

@param

int dirfd: is normally AT_FDCWD but if it's an open directory and path is relative, then path becomes relative to dirfd
const char* path: is a UTF-8 string, preferably relative w/ forward slashes
unsigned int mode: is permissions bits, which is usually 0755

@return

int: 0 on success, or -1 w/ errno

@raise EEXIST if named file already exists

@raise EBADF if path is relative and dirfd isn't AT_FDCWD or valid

@raise ENOTDIR if directory component in path existed as non-directory

@raise ENAMETOOLONG if symlink-resolved path length exceeds PATH_MAX

@raise ENAMETOOLONG if component in path exists longer than NAME_MAX

@raise EROFS if parent directory is on read-only filesystem

@raise ENOSPC if file system or parent directory is full

@raise EACCES if write permission was denied on parent directory

@raise EACCES if search permission was denied on component in path

@raise ENOENT if a component within path didn't exist

@raise ENOENT if path is an empty string

@raise ELOOP if loop was detected resolving components of path

@asyncsignalsafe

@see makedirs()

@see libc/calls/mkdirat.c

mkdtemp

Creates temporary directory, e.g.

char path[PATH_MAX];
snprintf(path, sizeof(path), "%s%s.XXXXXX",
         kTmpPath, program_invocation_short_name);
printf("%s\n", mkdtemp(path));
rmdir(path);

@param

char* template: must end with XXXXXX which is replaced with nondeterministic base36 random data

@return

char*: pointer to template on success, or NULL w/ errno

@raise EINVAL if template didn't end with XXXXXX

@see libc/stdio/mkdtemp.c

mkfifo

Creates named pipe.

@param

const char* pathname
unsigned int mode: is octal, e.g. 0600 for owner-only read/write

@return

int

@asyncsignalsafe

@see libc/calls/mkfifo.c

mknod

Creates filesystem inode.

@param

const char* path
unsigned int mode: is octal mode, e.g. 0600; needs to be or'd with one of: S_IFDIR: directory S_IFIFO: named pipe S_IFREG: regular file S_IFSOCK: named socket S_IFBLK: block device (root has authorization) S_IFCHR: character device (root has authorization)
unsigned long dev: it's complicated

@return

int: 0 on success, or -1 w/ errno

@asyncsignalsafe

@see libc/calls/mknod.c

mkntcmdline

@param

unsigned short* cmdline
char** argv

@return

int

@see libc/calls/mkntcmdline.c

mkntenvblock

Copies sorted environment variable block for Windows.

This is designed to meet the requirements of CreateProcess().

@param

unsigned short* envvars: receives sorted double-NUL terminated string list
char** envp: is an a NULL-terminated array of UTF-8 strings
const char* extravar: is a VAR=val string we consider part of envp or NULL
char* buf

@return

int: 0 on success, or -1 w/ errno

@error E2BIG if total number of shorts exceeded ARG_MAX/2 (32767)

@see libc/calls/mkntenvblock.c

__mkntpath2

Copies path for Windows NT.

This function does the following chores:

Converting UTF-8 to UTF-16
Replacing forward-slashes with backslashes
Fixing drive letter paths, e.g. /c/ → c:\
Add \\?\ prefix for paths exceeding 260 chars
Remapping well-known paths, e.g. /dev/null → NUL

@param

const char* path
unsigned short* path16: is shortened so caller can prefix, e.g. \\.\pipe\, and due to a plethora of special-cases throughout the Win32 API
int flags: is used by open()

@return

int: short count excluding NUL on success, or -1 w/ errno

@error ENAMETOOLONG

@see libc/calls/mkntpath.c

mkostemp

@param

char* template
unsigned int flags

@return

int

@see libc/stdio/mkostemp.c

mkostemps

Delegates to mkotempsm() w/ owner-only non-execute access.

@param

char* template
int suffixlen
unsigned int flags

@return

int

@see libc/stdio/mkostemps.c

mkostempsm

Opens unique temporary file.

The substring XXXXXX is replaced with a pseudorandom number that's seeded automatically and grants 30 bits of randomness to each value. Retries are made in the unlikely event of collisions.

@param

char* template: is a pathname relative to current directory by default, that needs to have "XXXXXX" at the end of the string
int suffixlen: may be nonzero to permit characters after the XXXXXX
unsigned int flags: can have O_APPEND, O_CLOEXEC, etc.
int mode: is conventionally 0600, for owner-only non-exec access

@return

int: exclusive open file descriptor for generated pathname, or -1 w/ errno

@see kTmpPath

@see libc/stdio/mkostempsm.c

mkostempsmi

@param

char* tpl
int slen
unsigned int flags
unsigned long* rando
int mode
int(*)() openit

@return

int

@see libc/stdio/mkostempsm.c

mkstemp

@param

char* template

@return

int

@see libc/stdio/mkstemp.c

mkstemps

@param

char* template
int suffixlen

@return

int

@see libc/stdio/mkstemps.c

mktemp

Generates unique filename.

This function is usually frowned upon, since it's been known to create nasty opportunities for race conditions. Our implementation reflects that; consider using mkostemps().

@param

char* template

@return

char*

@see libc/stdio/mktemp.c

mktime

@param

struct alttm* tmp

@return

long

@see libc/time/localtime.c

_mktls

Allocates thread-local storage memory for new thread.

@param

struct CosmoTib** out_tib

@return

char*: buffer that must be released with free()

@see libc/thread/mktls.c

mmap

Beseeches system for page-table entries, e.g.

char *m;
m = mmap(NULL, FRAMESIZE, PROT_READ | PROT_WRITE,
         MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);
munmap(m, FRAMESIZE);

@param

void* addr

should be 0 to let your memory manager choose address; unless MAP_FIXED or MAP_FIXED_NOREPLACE are specified in flags in which case this function will do precicely as you ask, even if p=0 (in which you need -fno-delete-null-pointer-checks); it needs to be 64kb aligned because it's a wise choice that sadly needs to be made mandatory because of Windows although you can use __sys_mmap() to circumvent it on System Five in which case runtime support services, e.g. asan memory safety, could break

unsigned long size

must be >0 and needn't be a multiple of FRAMESIZE, but will be rounded up to FRAMESIZE automatically if MAP_ANONYMOUS is specified

int prot

can have PROT_READ/PROT_WRITE/PROT_EXEC/PROT_NONE/etc.

int flags

should have one of the following masked by MAP_TYPE

MAP_FILE in which case fd != -1 should be the case
MAP_PRIVATE for copy-on-write behavior of writeable pages
MAP_SHARED to create shared memory between processes
MAP_STACK to create a grows-down alloc, where a guard page is automatically protected at the bottom: FreeBSD's behavior is polyfilled across platforms; uses MAP_GROWSDOWN on Linux too for extra oomph (do not use MAP_GROWSDOWN!) and this is completely mandatory on OpenBSD but helps perf elsewhere if you need to create 10,000 threads. This flag is the reason why STACK_FRAME_UNLIMITED toil is important, because this only allocates a 4096-byte guard page, thus we need the GCC compile-time checks to ensure some char[8192] vars will not create an undetectable overflow into another thread's stack

Your flags may optionally bitwise or any of the following:

MAP_ANONYMOUS in which case fd == -1 should be the case
MAP_FIXED in which case addr becomes more than a hint
MAP_FIXED_NOREPLACE to protect existing mappings; this is always polyfilled by mmap() which tracks its own memory and removed before passing to the kernel, in order to support old versions; if you believe mappings exist which only the kernel knows, then this flag may be passed to sys_mmap() on Linux 4.17+ and FreeBSD (where it has multiple bits)
MAP_CONCEAL is FreeBSD/NetBSD/OpenBSD-only
MAP_NORESERVE is Linux/XNU/NetBSD-only
MAP_POPULATE is Linux/FreeBSD-only
MAP_NONBLOCK is Linux-only
MAP_NOSYNC is FreeBSD-only
MAP_INHERIT is NetBSD-only
MAP_LOCKED is Linux-only

int fd

is an open()'d file descriptor, whose contents shall be made available w/ automatic reading at the chosen address and must be -1 if MAP_ANONYMOUS is specified

long off

specifies absolute byte index of fd's file for mapping, should be zero if MAP_ANONYMOUS is specified, and sadly needs to be 64kb aligned too

@return

void*: virtual base address of new mapping, or MAP_FAILED w/ errno

@see libc/runtime/mmap.c

Mmap

@param

void* addr
unsigned long size
int prot
int flags
int fd
long off

@return

void*

@see libc/runtime/mmap.c

modf

@param

double x
double* iptr

@return

double

@see libc/tinymath/modf.c

modff

@param

float x
float* iptr

@return

float

@see libc/tinymath/modff.c

__morph_begin

Begins code morphing executable.

@param

struct ss* save

@return

void: 0 on success, or -1 w/ errno

@see libc/runtime/morph.greg.c

__morph_end

Begins code morphing executable.

@param

struct ss* save

@return

void

@see libc/runtime/morph.greg.c

morton

Interleaves bits.

@param

unsigned long y
unsigned long x

@return

unsigned long

@see https://en.wikipedia.org/wiki/Z-order_curve

@see unmorton()

@see libc/intrin/morton.c

mount

Mounts file system.

The following flags may be specified:

MS_RDONLY (mount read-only)
MS_NOSUID (don't honor S_ISUID bit)
MS_NODEV (disallow special files)
MS_NOEXEC (disallow program execution)
MS_SYNCHRONOUS (writes are synced at once)
MS_NOATIME (do not update access times)
MS_REMOUNT (tune existing mounting)

The following flags may also be used, but could be set to zero at runtime if the underlying kernel doesn't support them.

MNT_ASYNC (xnu, freebsd, openbsd, netbsd)
MNT_RELOAD (xnu, freebsd, openbsd, netbsd)
MS_STRICTATIME (linux, xnu)
MS_RELATIME (linux, netbsd)
MNT_SNAPSHOT (xnu, freebsd)
MS_MANDLOCK (linux)
MS_DIRSYNC (linux)
MS_NODIRATIME (linux)
MS_BIND (linux)
MS_MOVE (linux)
MS_REC (linux)
MS_SILENT (linux)
MS_POSIXACL (linux)
MS_UNBINDABLE (linux)
MS_PRIVATE (linux)
MS_SLAVE (linux)
MS_SHARED (linux)
MS_KERNMOUNT (linux)
MS_I_VERSION (linux)
MS_LAZYTIME (linux)
MS_ACTIVE (linux)
MS_NOUSER (linux)
MS_RMT_MASK (linux)
MNT_SUIDDIR (freebsd)
MNT_NOCLUSTERR (freebsd)
MNT_NOCLUSTERW (freebsd)

Some example values for the type parameter:

"nfs"
"vfat"
"tmpfs"
"iso8601"

@param

const char* source
const char* target
const char* type
unsigned long flags
void* data

@return

int

@see libc/calls/mount.c

MoveFileEx

Deletes existing empty directory.

@param

const unsigned short* lpExistingFileName
const unsigned short* lpNewFileName
int dwFlags

@return

int

@note this wrapper takes care of ABI, STRACE(), and __winerr()

@see libc/intrin/movefileex.c

mprotect

Modifies restrictions on virtual memory address range.

@param

void* addr: needs to be 4kb aligned
unsigned long size
int prot: can have PROT_{NONE,READ,WRITE,EXEC,GROWSDOWN,GROWSUP}

@return

int: 0 on success, or -1 w/ errno

@see mmap()

@see libc/runtime/mprotect.c

mpsadbw

Computes multiple sum of absolute differences.

This appears to be intended for video encoding motion estimation. It can be combined with phminposuw. That allows us to search for an int overlapping inside 𝑏 that's nearest to an aligned int in 𝑎.

@param

unsigned short* c
const unsigned char* b
const unsigned char* a
unsigned char control

@return

void

@note goes fast w/ sse4 cf. core c. 2006 cf. bulldozer c. 2011

@mayalias

@see libc/intrin/mpsadbw.c

__mpsadbws

Jump table for mpsadbw() with non-constexpr immediate parameter.

@return

@note needs sse4 cf. core c. 2006 cf. bulldozer c. 2011

@see mpsadbw()

@see libc/intrin/mpsadbws.S

mrand48

@return

long

@see third_party/musl/rand48.c

mremap

Extends and/or relocates memory pages.

@param

void* p: is old address
unsigned long n: is old size
unsigned long m: is new size
int f: should have MREMAP_MAYMOVE and may have MAP_FIXED
...

@return

void*

@see libc/runtime/mremap.c

msync

Synchronize memory mapping changes to disk.

Without this, there's no guarantee memory is written back to disk. Particularly on RHEL5, OpenBSD, and Windows NT.

@param

void* addr: needs to be 4096-byte page aligned
unsigned long size
int flags: needs MS_ASYNC or MS_SYNC and can have MS_INVALIDATE

@return

int: 0 on success or -1 w/ errno

@raise ECANCELED if thread was cancelled in masked mode

@raise EINTR if we needed to block and a signal was delivered instead

@cancellationpoint

@see libc/runtime/msync.c

_mt19937

Generates random integer on [0, 2^64)-interval.

This uses the Mersenne Twister pseudorandom number generator.

@return

unsigned long

@see smt19937(), Smt19937()

@see libc/stdio/mt19937.c

Mul4x4Adx

Computes 512-bit product of 256-bit and 256-bit numbers.

Instructions: 88 Total Cycles: 36 Total uOps: 120 uOps Per Cycle: 3.33 IPC: 2.44 Block RThroughput: 20.0

@param

rdi: receives 8 quadword result
rsi: is left hand side which must have 4 quadwords
rdx: is right hand side which must have 4 quadwords

@return

@note words are host endian while array is little endian

@mayalias

@see libc/nexgen32e/mul4x4adx.S

Mul6x6Adx

Computes 768-bit product of 384-bit and 384-bit numbers.

Instructions: 152 Total Cycles: 65 Total uOps: 260 uOps Per Cycle: 4.00 IPC: 2.34 Block RThroughput: 43.3

@param

rdi: receives 8 quadword result
rsi: is left hand side which must have 4 quadwords
rdx: is right hand side which must have 4 quadwords

@return

@note words are host endian while array is little endian

@mayalias

@see libc/nexgen32e/mul6x6adx.S

Mul8x8Adx

Computes 1024-bit product of 512-bit and 512-bit numbers.

Instructions: 260 Total Cycles: 98 Total uOps: 452 uOps Per Cycle: 4.61 IPC: 2.65 Block RThroughput: 75.3

@param

rdi: receives 16 quadword result
rsi: is left hand side which must have 8 quadwords
rdx: is right hand side which must have 8 quadwords

@return

@note words are host endian while array is little endian

@mayalias

@see libc/nexgen32e/mul8x8adx.S

__mulvdi3

Returns 𝑥*𝑦, aborting on overflow.

@param

rdi: is int64 𝑥
rdi: is int64 𝑥

@return

: rax is 𝑥*𝑦

@see -ftrapv

@see libc/intrin/mulvdi3.S

__mulvsi3

Returns 𝑥*𝑦, aborting on overflow.

@param

edi: is int32 𝑥
esi: is int32 𝑦

@return

: eax is 𝑥*𝑦

@see -ftrapv

@see libc/intrin/mulvsi3.S

__mulvti3

Returns 𝑥*𝑦, aborting on overflow.

@param

rdi:rsi: is int128 𝑥
rdx:rcx: is int128 𝑦

@return

: rdx:rax is 𝑥*𝑦

@see -ftrapv

@see libc/intrin/mulvti3.S

Munmap

@param

char* p
unsigned long n

@return

int

@see libc/runtime/munmap.c

munmap

Releases memory pages.

@param

void* p: is the beginning of the memory region to unmap
unsigned long n: is the number of bytes to be unmapped

@return

int: 0 on success, or -1 w/ errno

@raises EINVAL if n == 0

@raises EINVAL if n isn't 48-bit

@raises EINVAL if p+(n-1) isn't 48-bit

@raises EINVAL if p isn't 65536-byte aligned

@see libc/runtime/munmap.c

nan

@param

const char* s

@return

double

@see libc/tinymath/nan.c

nanf

@param

const char* s

@return

float

@see libc/tinymath/nanf.c

nanl

@param

const char* s

@return

long double

@see libc/tinymath/nanl.c

_nanos

Returns nanoseconds since UNIX epoch.

@param

int timer

@return

__int128

@see libc/calls/nanos.c

nanosleep

Sleeps for relative amount of time.

@param

ANONYMOUS-STRUCT* req: is the duration of time we should sleep
ANONYMOUS-STRUCT* rem: if non-null will be updated with the remainder of unslept time when -1 w/ EINTR is returned otherwise rem is undefined

@return

int: 0 on success, or -1 w/ errno

@raise EINVAL if req->tv_nsec ∉ [0,1000000000)

@raise ECANCELED if thread was cancelled in masked mode

@raise EINTR if a signal was delivered and rem is updated

@raise EFAULT if req is NULL or req / rem is a bad pointer

@raise ENOSYS on bare metal

@see clock_nanosleep()

@cancellationpoint

@norestart

@see libc/calls/nanosleep.c

__negvdi2

Returns -𝑥, aborting on overflow (two's complement bane).

@param

rdi: is int64 𝑥

@return

: rax is -𝑥

@see -ftrapv

@see libc/intrin/negvdi2.S

__negvsi2

Returns -𝑥, aborting on overflow (two's complement bane).

@param

edi: is int32 𝑥

@return

: eax is -𝑥

@see -ftrapv

@see libc/intrin/negvsi2.S

__negvti2

Returns -𝑥, aborting on overflow.

@param

rdi:rsi: is int128 𝑥

@return

: rdx:rax is -𝑥

@see -ftrapv

@see libc/intrin/negvti2.S

__new_page

Allocates new page of physical memory.

@param

struct mman* mm

@return

unsigned long

@see libc/intrin/mman.greg.c

newaddrinfo

@param

unsigned short port

@return

struct addrinfo*

@see libc/dns/newaddrinfo.c

newlocale

@param

int catmask
const char* locale
struct __locale_struct* base

@return

struct __locale_struct*

@see libc/str/newlocale.c

nextafter

@param

double x
double y

@return

double

@see libc/tinymath/nextafter.c

nextafterf

@param

float x
float y

@return

float

@see libc/tinymath/nextafterf.c

nextafterl

@param

long double x
long double y

@return

long double

@see libc/tinymath/nextafterl.c

nexttoward

@param

double x
long double y

@return

double

@see libc/tinymath/nexttoward.c

nexttowardf

@param

float x
long double y

@return

float

@see libc/tinymath/nexttowardf.c

nexttowardl

@param

long double x
long double y

@return

long double

@see libc/tinymath/nexttowardl.c

nftw

Walks file tree.

@param

const char* path
int(*)() fn
int fd_limit
int flags

@return

int

@see examples/walk.c for example

@see third_party/musl/nftw.c

nice

Changes process priority.

@param

int delta: is added to current priority w/ clamping

@return

int: new priority, or -1 w/ errno

@see Linux claims ioprio_set() is tuned automatically by this

@see libc/calls/nice.c

nl_langinfo

@param

int item

@return

char*

@see libc/str/langinfo.c

nl_langinfo_l

@param

int item
struct __locale_struct* loc

@return

char*

@see libc/str/langinfo.c

__nocolor

Indicates if ANSI terminal colors are inappropriate.

Normally this variable should be false. We only set it to true if we're running on an old version of Windows or the environment variable TERM is set to dumb.

We think colors should be the norm, since most software is usually too conservative about removing them. Rather than using isatty consider using sed for instances where color must be removed:

 sed 's/\x1b\[[;[:digit:]]*m//g' <color.txt >uncolor.txt

For some reason, important software is configured by default in many operating systems, to not only disable colors, but utf-8 too! Here's an example of how a wrapper script can fix that for less.

 #!/bin/sh
 LESSCHARSET=UTF-8 exec /usr/bin/less -RS "$@"

Thank you for using colors!

@type

_Bool

@see libc/intrin/nocolor.c

__nosync

Tunes sync system call availability.

If this value is set to 0x5453455454534146, then the system calls sync(), fsync(), and fdatasync() system calls will do nothing and return success. This is intended to be used for things like making things like Python unit tests go faster because fsync is extremely slow and using tmpfs requires root privileges.

@type

unsigned long

@see libc/calls/nosync.c

nowl_setup

@return

long double

@see libc/calls/now.c

nrand48

@param

unsigned short* s

@return

long

@see third_party/musl/rand48.c

nsync_counter_add

@param

struct nsync_counter_s_* c
int delta

@return

unsigned int

@see third_party/nsync/mem/nsync_counter.c

nsync_counter_free

@param

struct nsync_counter_s_* c

@return

void

@see third_party/nsync/mem/nsync_counter.c

nsync_counter_new

@param

unsigned int value

@return

struct nsync_counter_s_*

@see third_party/nsync/mem/nsync_counter.c

nsync_counter_value

@param

struct nsync_counter_s_* c

@return

unsigned int

@see third_party/nsync/mem/nsync_counter.c

nsync_counter_wait

@param

struct nsync_counter_s_* c
struct abs_deadline abs_deadline

@return

unsigned int

@see third_party/nsync/mem/nsync_counter.c

nsync_counter_waitable_funcs

@type

struct nsync_counter_waitable_funcs

@see third_party/nsync/mem/nsync_counter.c

nsync_cv_broadcast

@param

struct no_children_cv* pcv

@return

void

@see third_party/nsync/mem/nsync_cv.c

nsync_cv_debug_state

@param

struct no_children_cv* cv
char* buf
int n

@return

char*

@see third_party/nsync/mem/nsync_debug.c

nsync_cv_debug_state_and_waiters

@param

struct no_children_cv* cv
char* buf
int n

@return

char*

@see third_party/nsync/mem/nsync_debug.c

nsync_cv_debugger

@param

struct no_children_cv* cv

@return

char*

@see third_party/nsync/mem/nsync_debug.c

nsync_cv_init

@param

struct no_children_cv* cv

@return

void

@see third_party/nsync/mem/nsync_cv.c

nsync_cv_signal

@param

struct no_children_cv* pcv

@return

void

@see third_party/nsync/mem/nsync_cv.c

nsync_cv_wait

@param

struct no_children_cv* pcv
struct note_mu* pmu

@return

int

@see third_party/nsync/mem/nsync_cv.c

nsync_cv_wait_with_deadline

@param

struct no_children_cv* pcv
struct note_mu* pmu
struct abs_deadline abs_deadline
struct nsync_note_s_* cancel_note

@return

int

@see third_party/nsync/mem/nsync_cv.c

nsync_cv_wait_with_deadline_generic

@param

struct no_children_cv* pcv
void* pmu
void(*)() lock
void(*)() unlock
struct abs_deadline abs_deadline
struct nsync_note_s_* cancel_note

@return

int

@see third_party/nsync/mem/nsync_cv.c

nsync_cv_waitable_funcs

@type

struct nsync_cv_waitable_funcs

@see third_party/nsync/mem/nsync_cv.c

nsync_mu_assert_held

@param

struct note_mu* mu

@return

void

@see third_party/nsync/mu.c

nsync_mu_debug_state

@param

struct note_mu* mu
char* buf
int n

@return

char*

@see third_party/nsync/mem/nsync_debug.c

nsync_mu_debug_state_and_waiters

@param

struct note_mu* mu
char* buf
int n

@return

char*

@see third_party/nsync/mem/nsync_debug.c

nsync_mu_debugger

@param

struct note_mu* mu

@return

char*

@see third_party/nsync/mem/nsync_debug.c

nsync_mu_init

@param

struct note_mu* mu

@return

void

@see third_party/nsync/mu.c

nsync_mu_is_reader

@param

struct note_mu* mu

@return

int

@see third_party/nsync/mu.c

nsync_mu_lock

@param

struct note_mu* mu

@return

void

@see third_party/nsync/mu.c

nsync_mu_rassert_held

@param

struct note_mu* mu

@return

void

@see third_party/nsync/mu.c

nsync_mu_rlock

@param

struct note_mu* mu

@return

void

@see third_party/nsync/mu.c

nsync_mu_rtrylock

@param

struct note_mu* mu

@return

int

@see third_party/nsync/mu.c

nsync_mu_runlock

@param

struct note_mu* mu

@return

void

@see third_party/nsync/mu.c

nsync_mu_trylock

@param

struct note_mu* mu

@return

int

@see third_party/nsync/mu.c

nsync_mu_unlock

@param

struct note_mu* mu

@return

void

@see third_party/nsync/mu.c

nsync_mu_unlock_without_wakeup

@param

struct note_mu* mu

@return

void

@see third_party/nsync/mem/nsync_mu_wait.c

nsync_mu_wait

@param

struct note_mu* mu
int(*)() condition
void* condition_arg
int(*)() condition_arg_eq

@return

void

@see third_party/nsync/mem/nsync_mu_wait.c

nsync_mu_wait_with_deadline

@param

struct note_mu* mu
int(*)() condition
void* condition_arg
int(*)() condition_arg_eq
struct abs_deadline abs_deadline
struct nsync_note_s_* cancel_note

@return

int

@see third_party/nsync/mem/nsync_mu_wait.c

nsync_note_expiry

@param

struct nsync_note_s_* n

@return

struct ntime

@see third_party/nsync/mem/nsync_note.c

nsync_note_free

@param

struct nsync_note_s_* n

@return

void

@see third_party/nsync/mem/nsync_note.c

nsync_note_is_notified

@param

struct nsync_note_s_* n

@return

int

@see third_party/nsync/mem/nsync_note.c

nsync_note_new

@param

struct nsync_note_s_* parent
struct abs_deadline abs_deadline

@return

struct nsync_note_s_*

@see third_party/nsync/mem/nsync_note.c

nsync_note_notify

@param

struct nsync_note_s_* n

@return

void

@see third_party/nsync/mem/nsync_note.c

nsync_note_wait

@param

struct nsync_note_s_* n
struct abs_deadline abs_deadline

@return

int

@see third_party/nsync/mem/nsync_note.c

nsync_note_waitable_funcs

@type

struct nsync_note_waitable_funcs

@see third_party/nsync/mem/nsync_note.c

nsync_run_once

@param

_Atomic unsigned int* once
void(*)() f

@return

void

@see third_party/nsync/mem/nsync_once.c

nsync_run_once_arg

@param

_Atomic unsigned int* once
void(*)() farg
void* arg

@return

void

@see third_party/nsync/mem/nsync_once.c

nsync_run_once_arg_spin

@param

_Atomic unsigned int* once
void(*)() farg
void* arg

@return

void

@see third_party/nsync/mem/nsync_once.c

nsync_run_once_spin

@param

_Atomic unsigned int* once
void(*)() f

@return

void

@see third_party/nsync/mem/nsync_once.c

__nt2sysv

Translates function call from code built w/ MS-style compiler.

This wraps WinMain() and callback functions passed to Win32 API. Please note an intermediary jump slot is needed to set %rax.

@param

%rax: is function address

@return

: %rax,%xmm0

@note slower than __sysv2nt

@see NT2SYSV() macro

@see libc/nexgen32e/nt2sysv.S

ntaccesscheck

Asks Microsoft if we're authorized to use a folder or file.

Implementation Details: MSDN documentation imposes no limit on the internal size of SECURITY_DESCRIPTOR, which we are responsible for allocating. We've selected 1024 which shall hopefully be adequate.

@param

const unsigned short* pathname
unsigned int flags: can have R_OK, W_OK, X_OK, etc.

@return

int: 0 if authorized, or -1 w/ errno

@see https://blog.aaronballman.com/2011/08/how-to-check-access-rights/

@see libc/sysv/consts.sh

@see libc/calls/ntaccesscheck.c

NtGetVersion

Returns New Technology version, e.g.

This can only be called on Windows.

@return

int

@see IsAtLeastWindows10()

@see libc/intrin/ntgetversion.c

ntohl

Converts network to host long.

@param

unsigned int x

@return

unsigned int

@see libc/sock/ntohl.c

ntohs

Converts network to host short.

@param

unsigned short x

@return

unsigned short

@see libc/sock/ntohs.c

ntreturn

Exitpoint for Windows NT system calls.

@param

unsigned int status

@return

long

@see libc/calls/ntreturn.c

ntsetprivilege

Sets NT permission thing, e.g.

int64_t htoken;
if (OpenProcessToken(GetCurrentProcess(),
                     kNtTokenAdjustPrivileges | kNtTokenQuery,
                     &htoken)) {
  ntsetprivilege(htoken, u"SeManageVolumePrivilege",
                 kNtSePrivilegeEnabled);
  CloseHandle(htoken);
}

@param

long token
const unsigned short* name
unsigned int attrs

@return

int

@see libc/calls/ntsetprivilege.c

ntspawn

Spawns process on Windows NT.

This function delegates to CreateProcess() with UTF-8 → UTF-16 translation and argv escaping. Please note this will NOT escape command interpreter syntax.

@param

const char* prog: won't be PATH searched
char** argv: specifies prog arguments
char** envp
const char* extravar: is added to envp to avoid setenv() in caller
struct NtSecurityAttributes* opt_lpProcessAttributes
struct NtSecurityAttributes* opt_lpThreadAttributes
int bInheritHandles: means handles already marked inheritable will be inherited; which, assuming the System V wrapper functions are being used, should mean (1) all files and sockets that weren't opened with O_CLOEXEC; and (2) all memory mappings
unsigned int dwCreationFlags
const unsigned short* opt_lpCurrentDirectory
struct NtStartupInfo* lpStartupInfo
struct NtProcessInformation* opt_out_lpProcessInformation: can be used to return process and thread IDs to parent, as well as open handles that need close()

@return

int: 0 on success, or -1 w/ errno

@see spawnve() which abstracts this function

@see libc/calls/ntspawn.c

__on_arithmetic_overflow

Arithmetic overflow handler.

@return

@see -ftrapv

@see libc/intrin/onarithmeticoverflow.S

__oncrash

Crashes in a developer-friendly human-centric way.

We first try to launch GDB if it's an interactive development session. Otherwise we show a really good crash report, sort of like Python, that includes filenames and line numbers. Many editors, e.g. Emacs, will even recognize its syntax for quick hopping to the failing line. That's only possible if the the .com.dbg file is in the same folder. If the concomitant debug binary can't be found, we simply print addresses which may be cross-referenced using objdump.

This function never returns, except for traps w/ human supervision.

@param

int sig
struct siginfo_t* si
struct ucontext_t* ctx

@return

void

@threadsafe

@vforksafe

@see libc/log/oncrash.c

open

Opens file.

This is equivalent to saying:

int fd = openat(AT_FDCWD, file, flags, ...);

@param

const char* file: specifies filesystem path to open
int flags
...

@return

int: file descriptor, or -1 w/ errno

@see openat() for further documentation

@cancellationpoint

@asyncsignalsafe

@restartable

@threadsafe

@vforksafe

@see libc/calls/open.c

openat

Opens file.

Here's an example of how a file can be created:

int fd = openat(AT_FDCWD, "hi.txt", O_CREAT | O_WRONLY | O_TRUNC, 0644);
write(fd, "hello\n", 6);
close(fd);

Here's an example of how that file could read back into memory:

char data[513] = {0};
int fd = openat(AT_FDCWD, "hi.txt", O_RDONLY);
read(fd, data, 512);
close(fd);
assert(!strcmp(data, "hello\n"));

If your main() source file has this statement:

STATIC_YOINK("zip_uri_support");

Then you can read zip assets by adding a "/zip/..." prefix to file, e.g.

// run `zip program.com hi.txt` beforehand
openat(AT_FDCWD, "/zip/hi.txt", O_RDONLY);

@param

int dirfd

is normally AT_FDCWD but if it's an open directory and file names a relative path then it's opened relative to dirfd

const char* file

is a UTF-8 string naming filesystem entity, e.g. foo/bar.txt, which on Windows is bludgeoned into a WIN32 path automatically, e.g.

foo/bar.txt becomes foo\bar.txt
/tmp/... becomes whatever GetTempPath() is
\\... or //... is passed through to WIN32 unchanged
/c/foo or \c\foo becomes \\?\c:\foo
c:/foo or c:\foo becomes \\?\c:\foo
/D becomes \\?\D:\

int flags

must have one of the following under the O_ACCMODE bits:

O_RDONLY to open file for reading only
O_WRONLY to open file for writing
O_RDWR to open file for reading and writing

The following may optionally be bitwise or'd into flags:

O_CREAT create file if it doesn't exist
O_TRUNC automatic ftruncate(fd,0) if exists
O_CLOEXEC automatic close() upon execve()
O_EXCL exclusive access (see below)
O_APPEND open file for appending only
O_EXEC open file for execution only; see fexecve()
O_NOCTTY prevents file possibly becoming controlling terminal
O_NONBLOCK asks read/write to fail with EAGAIN rather than block
O_DIRECT it's complicated (not supported on Apple and OpenBSD)
O_DIRECTORY useful for stat'ing (hint on UNIX but required on NT)
O_NOFOLLOW fail if it's a symlink (zero on Windows)
O_DSYNC it's complicated (zero on non-Linux/Apple)
O_RSYNC it's complicated (zero on non-Linux/Apple)
O_VERIFY it's complicated (zero on non-FreeBSD)
O_SHLOCK it's complicated (zero on non-BSD)
O_EXLOCK it's complicated (zero on non-BSD)
O_PATH open only for metadata (Linux 2.6.39+ otherwise zero)
O_NOATIME don't record access time (zero on non-Linux)
O_RANDOM hint random access intent (zero on non-Windows)
O_SEQUENTIAL hint sequential access intent (zero on non-Windows)
O_COMPRESSED ask fs to abstract compression (zero on non-Windows)
O_INDEXED turns on that slow performance (zero on non-Windows)
O_TMPFILE should not be used; use tmpfd() or tmpfile() instead

There are three regular combinations for the above flags:

O_RDONLY: Opens existing file for reading. If it doesn't exist then nil is returned and errno will be ENOENT (or in some other cases ENOTDIR).
O_WRONLY|O_CREAT|O_TRUNC: Creates file. If it already exists, then the existing copy is destroyed and the opened file will start off with a length of zero. This is the behavior of the traditional creat() system call.
O_WRONLY|O_CREAT|O_EXCL: Create file only if doesn't exist already. If it does exist then nil is returned along with errno set to EEXIST.

...

@return

int: file descriptor (which needs to be close()'d), or -1 w/ errno

@raise EPERM if pledge() is in play w/o appropriate rpath/wpath/cpath

@raise EACCES if unveil() is in play and didn't unveil your file path

@raise EACCES if we don't have permission to search a component of file

@raise EACCES if file exists but requested flags & O_ACCMODE was denied

@raise EACCES if file doesn't exist and parent dir lacks write permissions

@raise EACCES if O_TRUNC was specified in flags but writing was denied

@raise ENOTSUP if file is on zip file system and dirfd isn't AT_FDCWD

@raise ENOTDIR if a directory component in file exists as non-directory

@raise ENOTDIR if file is relative and dirfd isn't an open directory

@raise EROFS when writing is requested w/ file on read-only filesystem

@raise ENAMETOOLONG if symlink-resolved file length exceeds PATH_MAX

@raise ENAMETOOLONG if component in file exists longer than NAME_MAX

@raise ENOTSUP if file is on zip file system and process is vfork()'d

@raise ENOSPC if file system is full when file would be O_CREATed

@raise EINTR if we needed to block and a signal was delivered instead

@raise ECANCELED if thread was cancelled in masked mode

@raise ENOENT if file doesn't exist when O_CREAT isn't in flags

@raise ENOENT if file points to a string that's empty

@raise ENOMEM if insufficient memory was available

@raise EMFILE if process RLIMIT_NOFILE has been reached

@raise ENFILE if system-wide file limit has been reached

@raise EOPNOTSUPP if file names a named socket

@raise EFAULT if file points to invalid memory

@raise ETXTBSY if writing is requested on file that's being executed

@raise ELOOP if flags had O_NOFOLLOW and file is a symbolic link

@raise ELOOP if a loop was detected resolving components of file

@raise EISDIR if writing is requested and file names a directory

@cancellationpoint

@asyncsignalsafe

@restartable

@threadsafe

@vforksafe

@see libc/calls/openat.c

opendir

Opens directory, e.g.

DIR *d;
struct dirent *e;
CHECK((d = opendir(path)));
while ((e = readdir(d))) {
  printf("%s/%s\n", path, e->d_name);
}
LOGIFNEG1(closedir(d));

@param

const char* name

@return

struct dirstream*

@returns newly allocated DIR object, or NULL w/ errno

@errors ENOENT, ENOTDIR, EACCES, EMFILE, ENFILE, ENOMEM

@raise ECANCELED if thread was cancelled in masked mode

@raise EINTR if we needed to block and a signal was delivered instead

@cancellationpoint

@see glob()

@see libc/stdio/dirstream.c

OpenExecutable

Opens executable in O_RDWR mode.

To avoid ETXTBSY we need to unmap the running executable first, then open the file, and finally load the code back into memory.

@return

: file descriptor

@note only works on .com binary (not .com.dbg)

@note only supports linux, freebsd, openbsd, and netbsd

@see libc/runtime/openexecutable.S

openlog

Opens a connection to the system logger

Calling this function before calling syslog() is optional and only allow customizing the identity, options and facility of the messages logged.

@param

const char* ident

a string that prepends every logged message. If it set to NULL, the program name is used.

int opt

specifies flags which control the operation of openlog(). Only the following flags are supported:

LOG_CONS = Write directly to the system console if there is
           an error while sending to the system logger.
LOG_NDELAY = Open the connection with the system logger
             immediately instead of waiting for the first
             message to be logged.
LOG_ODELAY = The converse of LOG_NDELAY.
LOG_PERROR = Also log the message to stderr.
LOG_PID = Include the caller's PID with each message

int facility

specifies the default facitlity value that defines what kind of program is logging the message. Possible values are: LOG_AUTH, LOG_AUTHPRIV, LOG_CRON, LOG_DAEMON, LOG_FTP, LOG_LOCAL0 through LOG_LOCAL7, LOG_LPR, LOG_MAIL, LOG_NEWS, LOG_SYSLOG, LOG_USER (default), LOG_UUCP.

@return

void

@asyncsignalsafe

@see libc/sock/syslog.c

OpenProcess

Creates file mapping object on the New Technology.

@param

unsigned int dwDesiredAccess: should be kNtProcess... combination
int bInheritHandle
unsigned int dwProcessId

@return

long: ehandle, or 0 on failure

@note this wrapper takes care of ABI, STRACE(), and __winerr()

@see MapViewOfFileEx()

@see libc/intrin/openprocess.c

openpty

Opens new pseudo teletypewriter.

@param

int* mfd: receives controlling tty rw fd on success
int* sfd: receives subordinate tty rw fd on success
char* name
struct linux* tio: may be passed to tune a century of legacy behaviors
struct winsize* wsz: may be passed to set terminal display dimensions

@return

int: 0 on success, or -1 w/ errno

@params flags is usually O_RDWR|O_NOCTTY

@see libc/calls/openpty.c

OpenSymbolTable

Maps debuggable binary into memory and indexes symbol addresses.

@param

const char* filename

@return

struct SymbolTable*: object freeable with CloseSymbolTable(), or NULL w/ errno

@see libc/runtime/opensymboltable.greg.c

optarg

Argument associated with option.

@type

char*

@see getopt()

@see third_party/getopt/getopt.c

opterr

If error message should be printed.

@type

int

@see getopt()

@see third_party/getopt/getopt.c

optind

Index into parent argv vector.

@type

int

@see getopt()

@see third_party/getopt/getopt.c

optopt

Character checked for validity.

@type

int

@see getopt()

@see third_party/getopt/getopt.c

optreset

Reset getopt.

@type

int

@see getopt()

@see third_party/getopt/getopt.c

pabsb

Converts signed bytes to absolute values, 𝑎ᵢ ← |𝑏ᵢ|.

@param

unsigned char* a
const char* b

@return

void

@note goes fast w/ ssse3 (intel c. 2004, amd c. 2011)

@see libc/intrin/pabsb.c

pabsd

Converts shorts to absolute values, 𝑎ᵢ ← |𝑏ᵢ|.

@param

unsigned int* a
const int* b

@return

void

@note goes fast w/ ssse3 (intel c. 2004, amd c. 2011)

@see libc/intrin/pabsd.c

pabsw

Converts shorts to absolute values, 𝑎ᵢ ← |𝑏ᵢ|.

@param

unsigned short* a
const short* b

@return

void

@note goes fast w/ ssse3 (intel c. 2004, amd c. 2011)

@see libc/intrin/pabsw.c

packssdw

Casts ints to shorts w/ saturation.

@param

short* a
const int* b
const int* c

@return

void

@mayalias

@see libc/intrin/packssdw.c

packsswb

Casts shorts to signed chars w/ saturation.

𝑎 ← {CLAMP[𝑏ᵢ]|𝑖∈[0,4)} ║ {CLAMP[𝑐ᵢ]|𝑖∈[4,8)}

@param

char* a
const short* b
const short* c

@return

void

@see packuswb()

@mayalias

@see libc/intrin/packsswb.c

packusdw

Casts ints to shorts w/ saturation.

@param

unsigned short* a
const int* b
const int* c

@return

void

@mayalias

@see libc/intrin/packusdw.c

packuswb

Casts shorts to unsigned chars w/ saturation.

𝑎 ← {CLAMP[𝑏ᵢ]|𝑖∈[0,4)} ║ {CLAMP[𝑐ᵢ]|𝑖∈[4,8)}

@param

unsigned char* a
const short* b
const short* c

@return

void

@see packsswb()

@mayalias

@see libc/intrin/packuswb.c

paddb

Adds 8-bit integers.

@param

char* a
const char* b
const char* c

@return

void

@mayalias

@see libc/intrin/paddb.c

paddd

Adds 32-bit integers.

@param

unsigned int* a
const unsigned int* b
const unsigned int* c

@return

void

@mayalias

@see libc/intrin/paddd.c

paddq

Adds 64-bit integers.

@param

unsigned long* a
const unsigned long* b
const unsigned long* c

@return

void

@mayalias

@see libc/intrin/paddq.c

paddsb

Adds signed 8-bit integers w/ saturation.

@param

char* a
const char* b
const char* c

@return

void

@mayalias

@see libc/intrin/paddsb.c

paddsw

Adds signed 16-bit integers w/ saturation.

@param

short* a
const short* b
const short* c

@return

void

@mayalias

@see libc/intrin/paddsw.c

paddusb

Adds unsigned 8-bit integers w/ saturation.

@param

unsigned char* a
const unsigned char* b
const unsigned char* c

@return

void

@mayalias

@see libc/intrin/paddusb.c

paddusw

Adds unsigned 16-bit integers w/ saturation.

@param

unsigned short* a
const unsigned short* b
const unsigned short* c

@return

void

@mayalias

@see libc/intrin/paddusw.c

paddw

Adds 16-bit integers.

@param

short* a
const short* b
const short* c

@return

void

@note shorts can't overflow so ubsan won't report it when it happens

@see paddsw()

@mayalias

@see libc/intrin/paddw.c

__paginate

Displays wall of text in terminal with pagination.

@param

int fd
const char* s

@return

void

@see libc/stdio/paginate.c

palignr

Overlaps vectors.

𝑖= 0 means 𝑐←𝑎

0<𝑖<16 means 𝑐←𝑎║𝑏

𝑖=16 means 𝑐←𝑏

16<𝑖<32 means 𝑐←𝑏║0

𝑖≥32 means 𝑐←0

@param

void* c
void* b
void* a
unsigned long i

@return

void

@note not compatible with mmx

@see pvalignr()

@mayalias

@see libc/intrin/palignr.c

__palignrs

Jump table for palignr() with non-constexpr immediate parameter.

@return

@note needs ssse3 cf. prescott c. 2004 cf. bulldozer c. 2011

@see palignr()

@see libc/intrin/palignrs.S

pand

Ands 128-bit integers.

@param

unsigned long* a
const unsigned long* b
const unsigned long* c

@return

void

@mayalias

@see libc/intrin/pand.c

pandn

Nands 128-bit integers.

@param

unsigned long* a
const unsigned long* b
const unsigned long* c

@return

void

@mayalias

@see libc/intrin/pandn.c

ParseCidr

Parse IPv4 network address.

For example, a router address might be 10.10.10.1/24 in which case the IP address word 0x0a0a0a01 would be returned, whose CIDR would be 24. That means your IP address is on a network with 24 bits which converts to a netmask 0xffffff00 by using 1u << (32 - res.cidr). You may specify the IP address portion as an integer. As an example, the value 168430081/1 would be the same as 10.10.10.1/1

@param

const char* s
unsigned long n: if -1 implies strlen

@return

struct c: ip is uint32 IPv4 address, or -1 on failure; cidr is number of bits in network, on interval [1,32]; it defaults to 32; if the return ip is -1 then cidr is undefined

@see net/http/parsecidr.c

ParseContentLength

Parses Content-Length header.

@param

const char* s
unsigned long n

@return

long: -1 on invalid or overflow, otherwise >=0 value

@see net/http/parsecontentlength.c

ParseForwarded

Parses X-Forwarded-For.

This header is used by reverse proxies. For example:

X-Forwarded-For: 203.0.110.2, 203.0.113.42:31337

The port is optional and will be set to zero if absent.

@param

const char* s: is input data
unsigned long n: if -1 implies strlen
unsigned int* ip: receives last/right ip on success if not NULL
unsigned short* port: receives port on success if not NULL

@return

int: 0 on success or -1 on failure

@see RFC7239's poorly designed Forwarded header

@see net/http/parseforwarded.c

ParseHost

Parses HTTP Host header.

The input is ISO-8859-1 which is transcoded to UTF-8. Therefore we assume percent-encoded bytes are expressed as UTF-8. Returned values might contain things like NUL characters, C0, and C1 control codes. UTF-8 isn't checked for validity and may contain overlong values. Absent can be discerned from empty by checking if the pointer is set.

This function turns an HTTP header HOST[:PORT] into two strings, one for host and the other for port. You may then call IsAcceptableHost() and IsAcceptablePort() to see if they are valid values. After that a function like sscanf() can be used to do the thing you likely thought this function would do.

This function doesn't initialize h since it's assumed this will be called conditionally after ParseRequestUri() if the host is absent. Fields unrelated to authority won't be impacted by this function.

@param

const char* s: is value like 127.0.0.1 or foo.example:80
unsigned long n: is byte length and -1 implies strlen
struct Url* h: is needs to be initialized by caller

@return

char*: memory backing UrlView needing free

@see net/http/parseurl.c

ParseHostsTxt

Parses HOSTS.TXT contents.

Hostnames were invented by Peggy Karp; her format looks like this:

# this is a comment
# IP            CANON [ALT...]
203.0.113.1     lol.example. lol
203.0.113.2     cat.example. cat

@param

struct HostsTxt* ht
struct FILE* f: is the file content; see fopen() and fmemopen()

@return

int: 0 on success, or -1 w/ errno

@see hoststxtsort() which is the logical next step

@see libc/dns/parsehoststxt.c

ParseHttpDateTime

Parses HTTP timestamp, e.g.

Sun, 04 Oct 2020 19:50:10 GMT

@param

const char* p
unsigned long n: if -1 implies strlen

@return

long: seconds from unix epoch

@see FormatHttpDateTime()

@see net/http/parsehttpdatetime.c

ParseHttpMessage

Parses HTTP request or response.

This parser is responsible for determining the length of a message and slicing the strings inside it. Performance is attained using perfect hash tables. No memory allocation is performed for normal messages. Line folding is forbidden. State persists across calls so that fragmented messages can be handled efficiently. A limitation on message size is imposed to make the header data structures smaller.

This parser assumes ISO-8859-1 and guarantees no C0 or C1 control codes are present in message fields, with the exception of tab. Please note that fields like kHttpStateUri may use UTF-8 percent encoding. This parser doesn't care if you choose ASA X3.4-1963 or MULTICS newlines.

kHttpRepeatable defines which standard header fields are O(1) and which ones may have comma entries spilled over into xheaders. For most headers it's sufficient to simply check the static slice. If r->headers[kHttpFoo].a is zero then the header is totally absent.

This parser has linear complexity. Each character only needs to be considered a single time. That's the case even if messages are fragmented. If a message is valid but incomplete, this function will return zero so that it can be resumed as soon as more data arrives.

This parser takes about 400 nanoseconds to parse a 403 byte Chrome HTTP request under MODE=rel on a Core i9 which is about three cycles per byte or a gigabyte per second of throughput per core.

@param

struct HttpMessage* r
const char* p
unsigned long n

@return

int

@note we assume p points to a buffer that has >=SHRT_MAX bytes

@see HTTP/1.1 RFC2616 RFC2068

@see HTTP/1.0 RFC1945

@see net/http/parsehttpmessage.c

ParseHttpRange

Parses HTTP Range request header.

Here are some example values:

Range: bytes=0-                 (everything)
Range: bytes=0-499              (first 500 bytes)
Range: bytes=500-999            (second 500 bytes)
Range: bytes=-500               (final 500 bytes)
Range: bytes=0-0,-1             (first and last and always)
Range: bytes=500-600,601-999    (overlong but legal)

@param

const char* p
unsigned long n
long resourcelength
long* out_start
long* out_length

@return

_Bool

@see net/http/parsehttprange.c

ParseIp

Parse IPv4 host address.

@param

const char* s
unsigned long n: if -1 implies strlen

@return

long: -1 on failure, otherwise 32-bit host-order unsigned integer

@see ParseCidr()

@see net/http/parseip.c

ParseParams

Parses HTTP POST key-value params.

These are similar to the parameters found in a Request-URI, except usually submitted via an HTTP POST request. We translate + into space. The mime type is application/x-www-form-urlencoded.

This parser is charset agnostic. Returned values might contain things like NUL characters, NUL, control codes, and non-canonical encodings. Absent can be discerned from empty by checking if the pointer is set.

There's no failure condition for this routine. This is a permissive parser that doesn't impose character restrictions beyond what is necessary for parsing.

@param

const char* s: is value like foo=bar&x=y&z
unsigned long n: is byte length and -1 implies strlen
struct params* h: must be zeroed by caller and this appends if reused

@return

char*: UrlView memory with same n needing free (h.p needs free too)

@see net/http/parseurl.c

parseport

@param

const char* service

@return

int

@see libc/sock/parseport.c

ParsePromises

Parses the arguments to pledge() into a bitmask.

@param

const char* promises
unsigned long* out

@return

int: 0 on success, or -1 if invalid

@see libc/calls/parsepromises.c

ParseResolvConf

Parses /etc/resolv.conf file.

The content of the file usually looks like this:

nameserver 8.8.8.8
nameserver 8.8.4.4

@param

struct ResolvConf* resolv: points to a ResolvConf object, which should be zero initialized by the caller; or if it already contains items, this function will append
struct FILE* f: is an open stream with file content

@return

int: number of nameservers appended, or -1 w/ errno

@see libc/dns/parseresolvconf.c

ParseUrl

Parses URL.

This parser is charset agnostic. Percent encoded bytes are decoded for all fields (with the exception of scheme). Returned values might contain things like NUL characters, spaces, control codes, and non-canonical encodings. Absent can be discerned from empty by checking if the pointer is set.

There's no failure condition for this routine. This is a permissive parser. This doesn't normalize path segments like . or .. so use IsAcceptablePath() to check for those. No restrictions are imposed beyond that which is strictly necessary for parsing. All the s that is provided will be consumed to the one of the fields. Strict conformance is enforced on some fields more than others, like scheme, since it's the most non-deterministically defined field of them all.

Please note this is a URL parser, not a URI parser. Which means we support everything the URI spec says we should do except for the things we won't do, like tokenizing path segments into an array and then nesting another array beneath each of those for storing semicolon parameters. So this parser won't make SIP easy. What it can do is parse HTTP URLs and most URIs like s:opaque, better in fact than most things which claim to be URI parsers.

@param

const char* s

is value like /hi?x=y&z or http://a.example/hi#x

unsigned long n

is byte length and -1 implies strlen

struct Url* h

is assumed to be uninitialized

int f

is flags which may have:

FLAGS_PLUS to turn + into space in query params
FLAGS_LATIN1 to transcode ISO-8859-1 input into UTF-8

@return

char*: memory backing UrlView needing free (and h.params.p too)

@see URI Generic Syntax RFC3986 RFC2396

@see EncodeUrl()

@see net/http/parseurl.c

PascalifyDnsName

Writes dotted hostname to DNS message wire.

The wire format is basically a sequence of Pascal strings, for each label in the name. We only do enough validation to maintain protocol invariants.

@param

unsigned char* buf
unsigned long size
const char* name: is a dotted NUL-terminated hostname string

@return

int: bytes written (excluding NUL) or -1 w/ errno

@see libc/dns/pascalifydnsname.c

pathconf

@param

const char* path
int name

@return

long

@see libc/runtime/fpathconf.c

pause

Waits for signal.

This suspends execution until an unmasked signal is delivered. If the signal delivery kills the process, this won't return. The signal mask of the current thread is used. If a signal handler exists, this shall return after it's been invoked.

This function is equivalent to:

select(0, 0, 0, 0, 0);

However this has a tinier footprint and better logging.

@return

int: -1 w/ errno set to EINTR

@cancellationpoint

@see sigsuspend()

@norestart

@see libc/calls/pause.c

pavgb

Averages packed 8-bit unsigned integers w/ rounding.

@param

unsigned char* a
const unsigned char* b
const unsigned char* c

@return

void

@mayalias

@see libc/intrin/pavgb.c

pavgw

Averages packed 16-bit unsigned integers w/ rounding.

@param

unsigned short* a
const unsigned short* b
const unsigned short* c

@return

void

@mayalias

@see libc/intrin/pavgw.c

pclose

Closes stream created by popen().

This function may be interrupted or cancelled, however it won't actually return until the child process has terminated. Thus we always release the resource, and errors are purely advisory.

@param

struct FILE* f

@return

int: termination status of subprocess, or -1 w/ ECHILD

@raise ECANCELED if thread was cancelled in masked mode

@raise ECHILD if child pid didn't exist

@raise EINTR if signal was delivered

@cancellationpoint