mirrors/cosmopolitan
1
0
Fork 0
mirror of https://github.com/jart/cosmopolitan.git synced 2025-07-07 11:48:30 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Improve documentation

Browse source 
The Cosmo API documentation page is pretty good now
https://justine.lol/cosmopolitan/documentation.html
This commit is contained in:
Justine Tunney 2020-12-27 07:02:35 -08:00
parent 13437dd19b
commit 1bc3a25505
367 changed files with 2542 additions and 26178 deletions
Download patch file Download diff file Expand all files Collapse all files

2
libc/runtime/closesymboltable.c
View file

@ -18,7 +18,7 @@
│ 02110-1301 USA │
╚─────────────────────────────────────────────────────────────────────────────*/
#include "libc/calls/calls.h"
#include "libc/runtime/ezmap.h"
#include "libc/runtime/ezmap.internal.h"
#include "libc/runtime/runtime.h"
#include "libc/runtime/symbols.internal.h"

14
libc/runtime/directmap.c
View file

@ -21,12 +21,20 @@
#include "libc/nt/runtime.h"
#include "libc/runtime/directmap.h"
struct DirectMap DirectMap(void *addr, size_t size, unsigned prot,
unsigned flags, int fd, int64_t off) {
/**
* Obtains memory mapping directly from system.
*
* The mmap() function needs to track memory mappings in order to
* support Windows NT and Address Sanitizer. That memory tracking can be
* bypassed by calling this function. However the caller is responsible
* for passing the magic memory handle on Windows NT to CloseHandle().
*/
struct DirectMap __mmap(void *addr, size_t size, unsigned prot, unsigned flags,
int fd, int64_t off) {
if (!IsWindows()) {
return (struct DirectMap){mmap$sysv(addr, size, prot, flags, fd, off),
kNtInvalidHandleValue};
} else {
return DirectMapNt(addr, size, prot, flags, fd, off);
return __mmap$nt(addr, size, prot, flags, fd, off);
}
}

4
libc/runtime/directmap.h
View file

@ -8,8 +8,8 @@ struct DirectMap {
int64_t maphandle;
};
struct DirectMap DirectMap(void *, size_t, unsigned, unsigned, int, int64_t);
struct DirectMap DirectMapNt(void *, size_t, unsigned, unsigned, int, int64_t);
struct DirectMap __mmap(void *, size_t, unsigned, unsigned, int, int64_t);
struct DirectMap __mmap$nt(void *, size_t, unsigned, unsigned, int, int64_t);
COSMOPOLITAN_C_END_
#endif /* !(__ASSEMBLER__ + __LINKER__ + 0) */

4
libc/runtime/directmapnt.c
View file

@ -23,8 +23,8 @@
#include "libc/nt/runtime.h"
#include "libc/runtime/directmap.h"
textwindows struct DirectMap DirectMapNt(void *addr, size_t size, unsigned prot,
unsigned flags, int fd, int64_t off) {
textwindows struct DirectMap __mmap$nt(void *addr, size_t size, unsigned prot,
unsigned flags, int fd, int64_t off) {
int64_t handle;
struct DirectMap res;
if (fd != -1) {

15
libc/runtime/ezmap.c
View file

@ -17,20 +17,16 @@
│ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA │
│ 02110-1301 USA │
╚─────────────────────────────────────────────────────────────────────────────*/
#include "libc/bits/safemacros.internal.h"
#include "libc/bits/safemacros.h"
#include "libc/calls/calls.h"
#include "libc/limits.h"
#include "libc/runtime/ezmap.h"
#include "libc/runtime/ezmap.internal.h"
#include "libc/runtime/runtime.h"
#include "libc/sysv/consts/map.h"
#include "libc/sysv/consts/o.h"
#include "libc/sysv/consts/prot.h"
/**
* Memory-maps file for reading.
* An internal veneer for a common mmap() use-case.
*/
int MapFileRead(const char *filename, struct MappedFile *mf) {
hidden int MapFileRead(const char *filename, struct MappedFile *mf) {
mf->addr = MAP_FAILED;
if ((mf->fd = open(filename, O_RDONLY)) != -1 &&
(mf->size = getfiledescriptorsize(mf->fd)) < INT_MAX &&
@ -44,10 +40,7 @@ int MapFileRead(const char *filename, struct MappedFile *mf) {
}
}
/**
* Releases resource returned by MapFileRead().
*/
int UnmapFile(struct MappedFile *mf) {
hidden int UnmapFile(struct MappedFile *mf) {
int rc;
rc = 0;
if (mf->addr && mf->addr != MAP_FAILED) {

6
libc/runtime/ezmap.h → libc/runtime/ezmap.internal.h
View file

@ -1,5 +1,5 @@
#ifndef COSMOPOLITAN_LIBC_EZMAP_H_
#define COSMOPOLITAN_LIBC_EZMAP_H_
#ifndef COSMOPOLITAN_LIBC_RUNTIME_EZMAP_INTERNAL_H_
#define COSMOPOLITAN_LIBC_RUNTIME_EZMAP_INTERNAL_H_
#if !(__ASSEMBLER__ + __LINKER__ + 0)
COSMOPOLITAN_C_START_
@ -14,4 +14,4 @@ int UnmapFile(struct MappedFile *) hidden;
COSMOPOLITAN_C_END_
#endif /* !(__ASSEMBLER__ + __LINKER__ + 0) */
#endif /* COSMOPOLITAN_LIBC_EZMAP_H_ */
#endif /* COSMOPOLITAN_LIBC_RUNTIME_EZMAP_INTERNAL_H_ */

17
libc/runtime/ftrace.greg.c
View file

@ -19,7 +19,7 @@
╚─────────────────────────────────────────────────────────────────────────────*/
#include "libc/alg/bisectcarleft.internal.h"
#include "libc/bits/bits.h"
#include "libc/bits/safemacros.internal.h"
#include "libc/bits/safemacros.h"
#include "libc/calls/calls.h"
#include "libc/calls/internal.h"
#include "libc/calls/struct/sigset.h"
@ -100,15 +100,14 @@ privileged interruptfn void ftrace_hook(void) {
}
/**
* Enables plaintext function tracing if --ftrace flag passed.
* 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. Have fun.
* 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.
*
* @see libc/runtime/_init.S for documentation
*/

2
libc/runtime/getdosargv.c
View file

@ -20,7 +20,7 @@
#include "libc/assert.h"
#include "libc/bits/bits.h"
#include "libc/bits/pushpop.h"
#include "libc/bits/safemacros.internal.h"
#include "libc/bits/safemacros.h"
#include "libc/runtime/internal.h"
#include "libc/str/str.h"
#include "libc/str/tpenc.h"

34
libc/runtime/grow.c
View file

@ -27,40 +27,20 @@
#include "libc/str/str.h"
#include "libc/sysv/errfuns.h"
/* TODO(jart): DELETE */
#define GUARANTEE_TERMINATOR 1
#define INITIAL_CAPACITY (32 - GUARANTEE_TERMINATOR)
/**
* Grows array, The Cosmopolitan Way.
*
* This function may be called once an array has run out of space. If p
* is NULL, a new array is allocated; otherwise, the array's made 1.5x
* bigger. It has been written that this amortizes list appends down to
* constant-time. Extended memory is zeroed. Growth is monotonic.
*
* If p points to to static memory or something on the stack, it'll be
* converted to dynamic memory automatically. This can make algorithms
* faster when the average case is a small amount of data. It also means
* functions using this (and free_s()) won't have a hard-requirement on
* malloc().
*
* Consider trying the higher-level append() and concat() APIs (defined
* in libc/alg/arraylist.h) as an alternative to directly using grow().
*
* @param pp points to pointer holding memory address
* @param capacity tracks maximum items that can be stored in p
* can only be 0 if p is NULL (see reallocarray() for non-monotonic)
* @param itemsize is the sizeof each item
* @return true on success, or false w/ errno and *p is NOT free()'d
* @error ENOMEM if realloc() not linked or mmap() failed
* @note tiny programs might need to explicitly YOINK(realloc)
* @see test/libc/runtime/grow_test.c
* Grows array.
* @deprecated favor realloc
*/
bool __grow(void *pp, size_t *capacity, size_t itemsize, size_t extra) {
void **p, *p1, *p2;
size_t n1, n2; /* item counts */
size_t t1, t2; /* byte counts */
extra += GUARANTEE_TERMINATOR; /* p ⊃ p[𝑖]==0 */
size_t n1, n2;
size_t t1, t2;
extra += GUARANTEE_TERMINATOR;
p = (void **)pp;
assert(itemsize);
assert((*p && *capacity) || (!*p && !*capacity));

2
libc/runtime/internal.h
View file

@ -3,7 +3,7 @@
#ifndef __STRICT_ANSI__
#include "libc/dce.h"
#include "libc/elf/struct/ehdr.h"
#include "libc/runtime/ezmap.h"
#include "libc/runtime/ezmap.internal.h"
#include "libc/runtime/runtime.h"
#define STACK_CEIL 0x700000000000ul

2
libc/runtime/interruptiblecall.c
View file

@ -18,7 +18,7 @@
│ 02110-1301 USA │
╚─────────────────────────────────────────────────────────────────────────────*/
#include "libc/bits/progn.internal.h"
#include "libc/bits/safemacros.internal.h"
#include "libc/bits/safemacros.h"
#include "libc/mem/mem.h"
#include "libc/runtime/interruptiblecall.h"
#include "libc/runtime/runtime.h"

3
libc/runtime/isheap.c
View file

@ -29,7 +29,8 @@
*/
bool isheap(void *p) {
int x, i;
register uintptr_t rsp asm("rsp");
uintptr_t rsp;
asm("mov\t%%rsp,%0" : "=r"(rsp));
if (ROUNDDOWN(rsp, STACKSIZE) == ROUNDDOWN((intptr_t)p, STACKSIZE)) {
return false;
} else {

10
libc/runtime/mapanon.c
View file

@ -22,6 +22,16 @@
#include "libc/sysv/consts/map.h"
#include "libc/sysv/consts/prot.h"
/**
* Helper function for allocating anonymous mapping.
*
* This function is equivalent to:
*
* mmap(NULL, mapsize, PROT_READ | PROT_WRITE,
* MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);
*
* Except it offers a small saving on code size.
*/
void *mapanon(size_t mapsize) {
return mmap(NULL, mapsize, PROT_READ | PROT_WRITE,
MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);

4
libc/runtime/mapelfread.c
View file

@ -19,10 +19,10 @@
╚─────────────────────────────────────────────────────────────────────────────*/
#include "libc/elf/def.h"
#include "libc/elf/elf.h"
#include "libc/runtime/ezmap.h"
#include "libc/runtime/ezmap.internal.h"
#include "libc/runtime/internal.h"
Elf64_Ehdr *MapElfRead(const char *filename, struct MappedFile *mf) {
hidden Elf64_Ehdr *MapElfRead(const char *filename, struct MappedFile *mf) {
if (MapFileRead(filename, mf) != -1 && IsElf64Binary(mf->addr, mf->size)) {
return mf->addr;
} else {

2
libc/runtime/mmap.c
View file

@ -84,7 +84,7 @@ void *mmap(void *addr, size_t size, int prot, int flags, int fd, int64_t off) {
}
addr = (void *)(intptr_t)((int64_t)x << 16);
}
dm = DirectMap(addr, size, prot, flags | MAP_FIXED, fd, off);
dm = __mmap(addr, size, prot, flags | MAP_FIXED, fd, off);
if (dm.addr == MAP_FAILED || dm.addr != addr) {
return MAP_FAILED;
}

37
libc/runtime/ntgetmodule.c
View file

@ -1,37 +0,0 @@
/*-*- mode:c;indent-tabs-mode:nil;c-basic-offset:2;tab-width:8;coding:utf-8 -*-│
│vi: set net ft=c ts=8 sts=2 sw=2 fenc=utf-8 :vi│
╞══════════════════════════════════════════════════════════════════════════════╡
│ Copyright 2020 Justine Alexandra Roberts Tunney │
│ │
│ This program is free software; you can redistribute it and/or modify │
│ it under the terms of the GNU General Public License as published by │
│ the Free Software Foundation; version 2 of the License. │
│ │
│ This program is distributed in the hope that it will be useful, but │
│ WITHOUT ANY WARRANTY; without even the implied warranty of │
│ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU │
│ General Public License for more details. │
│ │
│ You should have received a copy of the GNU General Public License │
│ along with this program; if not, write to the Free Software │
│ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA │
│ 02110-1301 USA │
╚─────────────────────────────────────────────────────────────────────────────*/
#include "libc/nt/ntdll.h"
#include "libc/nt/struct/ldr.h"
#include "libc/nt/struct/ldrdatatableentry.h"
#include "libc/nt/struct/linkedlist.h"
#include "libc/nt/struct/teb.h"
#include "libc/str/str.h"
textwindows const struct NtLdrDataTableEntry *NtGetModule(
const char *basename) {
struct NtLinkedList *head = &NtGetPeb()->Ldr->InLoadOrderModuleList;
struct NtLinkedList *ldr = head->Next;
do {
const struct NtLdrDataTableEntry *dll =
(const struct NtLdrDataTableEntry *)ldr;
if (strcasecmp8to16(basename, dll->BaseDllName.Data) == 0) return dll;
} while ((ldr = ldr->Next) && ldr != head);
return NULL;
}

2
libc/runtime/piro.c
View file

@ -33,7 +33,7 @@
╠──────────────────────────────────────────────────────▌▀▄─▐──▀▄─▐▄─▐▄▐▄─▐▄─▐▄─│
│ αcτµαlly pδrταblε εxεcµταblε § post-initialization read-only │
╚─────────────────────────────────────────────────────────────────────────────*/
#include "libc/bits/safemacros.internal.h"
#include "libc/bits/safemacros.h"
#include "libc/bits/weaken.h"
#include "libc/calls/calls.h"
#include "libc/runtime/internal.h"

17
libc/runtime/ring.h
View file

@ -1,17 +0,0 @@
#ifndef COSMOPOLITAN_LIBC_RUNTIME_RING_H_
#define COSMOPOLITAN_LIBC_RUNTIME_RING_H_
#if !(__ASSEMBLER__ + __LINKER__ + 0)
COSMOPOLITAN_C_START_
struct RingBuffer {
void *p;
char *_addr;
size_t _size;
};
void *ringalloc(struct RingBuffer *, size_t);
int ringfree(struct RingBuffer *);
COSMOPOLITAN_C_END_
#endif /* !(__ASSEMBLER__ + __LINKER__ + 0) */
#endif /* COSMOPOLITAN_LIBC_RUNTIME_RING_H_ */

75
libc/runtime/ringalloc.c
View file

@ -1,75 +0,0 @@
/*-*- mode:c;indent-tabs-mode:nil;c-basic-offset:2;tab-width:8;coding:utf-8 -*-│
│vi: set net ft=c ts=2 sts=2 sw=2 fenc=utf-8 :vi│
╞══════════════════════════════════════════════════════════════════════════════╡
│ Copyright 2020 Justine Alexandra Roberts Tunney │
│ │
│ This program is free software; you can redistribute it and/or modify │
│ it under the terms of the GNU General Public License as published by │
│ the Free Software Foundation; version 2 of the License. │
│ │
│ This program is distributed in the hope that it will be useful, but │
│ WITHOUT ANY WARRANTY; without even the implied warranty of │
│ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU │
│ General Public License for more details. │
│ │
│ You should have received a copy of the GNU General Public License │
│ along with this program; if not, write to the Free Software │
│ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA │
│ 02110-1301 USA │
╚─────────────────────────────────────────────────────────────────────────────*/
#include "libc/assert.h"
#include "libc/calls/calls.h"
#include "libc/dce.h"
#include "libc/limits.h"
#include "libc/macros.h"
#include "libc/runtime/ring.h"
#include "libc/runtime/runtime.h"
#include "libc/str/str.h"
#include "libc/sysv/consts/map.h"
#include "libc/sysv/consts/prot.h"
/**
* Allocates ring buffer.
*
* Reads/writes wrap around on overflow.
*
* ┌────────────┐
* │ 𝑓₀..𝑓ₙ₋₁ │
* └┬┬──────────┘
* │└────────────┐
* ┌┴────────────┬┴────────────┐
* │ 𝑣₀..𝑣ₙ₋₁ │ 𝑣ₙ..𝑣ₙ*₂₋₁ │
* └─────────────┴─────────────┘
*
* @param r is metadata object owned by caller, initialized to zero
* @param n is byte length
* @return r->p, or NULL w/ errno
* @see ringfree(), balloc()
*/
void *ringalloc(struct RingBuffer *r, size_t n) {
void *a2;
int fd, rc;
size_t grain;
assert(!r->p);
assert(n > 0);
assert(n <= (INT_MAX - FRAMESIZE + 1) / 2);
if ((fd = openanon("ring", 0)) != -1) {
grain = ROUNDUP(n, FRAMESIZE);
rc = ftruncate(fd, grain * 2);
assert(rc != -1);
r->_size = grain * 2;
r->_addr = mmap(NULL, grain, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
if (r->_addr != MAP_FAILED) {
a2 = mmap(r->_addr + grain, grain, PROT_READ | PROT_WRITE,
MAP_SHARED | MAP_FIXED, fd, grain - n);
assert(a2 != MAP_FAILED);
r->p = r->_addr + grain - n;
if (IsWindows()) {
memset(r->p, 0, n); /* @see ftruncate() */
}
}
}
rc = close(fd);
assert(rc != -1);
return r->p;
}

35
libc/runtime/ringfree.c
View file

@ -1,35 +0,0 @@
/*-*- mode:c;indent-tabs-mode:nil;c-basic-offset:2;tab-width:8;coding:utf-8 -*-│
│vi: set net ft=c ts=2 sts=2 sw=2 fenc=utf-8 :vi│
╞══════════════════════════════════════════════════════════════════════════════╡
│ Copyright 2020 Justine Alexandra Roberts Tunney │
│ │
│ This program is free software; you can redistribute it and/or modify │
│ it under the terms of the GNU General Public License as published by │
│ the Free Software Foundation; version 2 of the License. │
│ │
│ This program is distributed in the hope that it will be useful, but │
│ WITHOUT ANY WARRANTY; without even the implied warranty of │
│ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU │
│ General Public License for more details. │
│ │
│ You should have received a copy of the GNU General Public License │
│ along with this program; if not, write to the Free Software │
│ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA │
│ 02110-1301 USA │
╚─────────────────────────────────────────────────────────────────────────────*/
#include "libc/runtime/ring.h"
#include "libc/runtime/runtime.h"
/**
* Frees ring buffer.
*
* @return 0 on success, or -1 w/ errno
*/
int ringfree(struct RingBuffer *r) {
if (r->p) {
r->p = NULL;
return munmap(r->_addr, r->_size);
} else {
return 0;
}
}

2
libc/runtime/symbols.internal.h
View file

@ -1,7 +1,7 @@
#ifndef COSMOPOLITAN_LIBC_SYMBOLS_H_
#define COSMOPOLITAN_LIBC_SYMBOLS_H_
#include "libc/elf/elf.h"
#include "libc/runtime/ezmap.h"
#include "libc/runtime/ezmap.internal.h"
#if !(__ASSEMBLER__ + __LINKER__ + 0)
COSMOPOLITAN_C_START_

2
libc/runtime/unsetenv.c
View file

@ -17,7 +17,7 @@
│ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA │
│ 02110-1301 USA │
╚─────────────────────────────────────────────────────────────────────────────*/
#include "libc/bits/safemacros.internal.h"
#include "libc/bits/safemacros.h"
#include "libc/runtime/runtime.h"
#include "libc/str/str.h"
#include "libc/sysv/errfuns.h"