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

Auto-generate some documentation

Browse source
This commit is contained in:
Justine Tunney 2020-12-26 02:09:07 -08:00
parent 117d0111ab
commit 13437dd19b
97 changed files with 2033 additions and 661 deletions
Download patch file Download diff file Expand all files Collapse all files

12
libc/calls/fchmod.c
View file

@ -25,15 +25,15 @@
/**
* Changes file permissions via open()'d file descriptor, 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));
* 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 V 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
* 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
*
* This works on Windows NT if you ignore the error ;-)
*

2
libc/calls/fcntl.c
View file

@ -24,7 +24,7 @@
/**
* Does things with file descriptor, via re-imagined hourglass api, e.g.
*
* CHECK_NE(-1, fcntl(fd, F_SETFD, FD_CLOEXEC));
* CHECK_NE(-1, fcntl(fd, F_SETFD, FD_CLOEXEC));
*
* @param cmd can be F_{GET,SET}{FD,FL}, etc.
* @param arg can be FD_CLOEXEC, etc. depending

14
libc/calls/hefty/dirstream.c
View file

@ -118,13 +118,13 @@ static textwindows noinline struct dirent *readdir$nt(DIR *dir) {
/**
* 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));
* DIR *d;
* struct dirent *e;
* CHECK((d = opendir(path)));
* while ((e = readdir(d))) {
* printf("%s/%s\n", path, e->d_name);
* }
* LOGIFNEG1(closedir(d));
*
* @returns newly allocated DIR object, or NULL w/ errno
* @errors ENOENT, ENOTDIR, EACCES, EMFILE, ENFILE, ENOMEM

25
libc/calls/hefty/spawnve.c
View file

@ -27,18 +27,18 @@
/**
* Launches program, e.g.
*
* char buf[2];
* int ws, pid, fds[3] = {-1, -1, STDERR_FILENO};
* CHECK_NE(-1, (pid = spawnve(0, fds, commandv("ssh"),
* (char *const[]){"ssh", hostname, "cat", NULL},
* environ)));
* CHECK_EQ(+2, write(fds[0], "hi", 2));
* CHECK_NE(-1, close(fds[0]));
* CHECK_EQ(+2, read(fds[1], buf, 2)));
* CHECK_NE(-1, close(fds[1]));
* CHECK_EQ(+0, memcmp(buf, "hi", 2)));
* CHECK_NE(-1, waitpid(pid, &ws, 0));
* CHECK_EQ(+0, WEXITSTATUS(ws));
* char buf[2];
* int ws, pid, fds[3] = {-1, -1, STDERR_FILENO};
* CHECK_NE(-1, (pid = spawnve(0, fds, commandv("ssh"),
* (char *const[]){"ssh", hostname, "cat", 0},
* environ)));
* CHECK_EQ(+2, write(fds[0], "hi", 2));
* CHECK_NE(-1, close(fds[0]));
* CHECK_EQ(+2, read(fds[1], buf, 2)));
* CHECK_NE(-1, close(fds[1]));
* CHECK_EQ(+0, memcmp(buf, "hi", 2)));
* CHECK_NE(-1, waitpid(pid, &ws, 0));
* CHECK_EQ(+0, WEXITSTATUS(ws));
*
* @param stdiofds may optionally be passed to customize standard i/o
* @param stdiofds[𝑖] may be -1 to receive a pipe() fd
@ -49,6 +49,7 @@
* @param envp[0,n-2] specifies "foo=bar" environment variables
* @param envp[n-1] is NULL
* @return pid of child, or -1 w/ errno
* @deprecated just use vfork() and execve()
*/
int spawnve(unsigned flags, int stdiofds[3], const char *program,
char *const argv[], char *const envp[]) {

2
libc/calls/isatty.c
View file

@ -27,7 +27,7 @@
* @asyncsignalsafe
*/
bool32 isatty(int fd) {
char buf[sizeof(uint16_t) * 4] forcealign(2);
_Alignas(short) char buf[sizeof(uint16_t) * 4];
if (!IsWindows()) {
return ioctl$sysv(fd, TIOCGWINSZ, &buf) != -1;
} else {

55
libc/calls/kntprioritycombos.c
View file

@ -21,38 +21,37 @@
#include "libc/calls/kntprioritycombos.internal.h"
#include "libc/limits.h"
#include "libc/macros.h"
#include "libc/nexgen32e/ffs.h"
#include "libc/nt/enum/processcreationflags.h"
#include "libc/nt/enum/threadpriority.h"
#define FFS(x) __builtin_ffs(x)
const struct NtPriorityCombo kNtPriorityCombos[] = {
{-20, FFS(kNtHighPriorityClass), kNtThreadPriorityHighest, 15},
{-18, FFS(kNtHighPriorityClass), kNtThreadPriorityTimeCritical, 15},
{-17, FFS(kNtNormalPriorityClass), kNtThreadPriorityTimeCritical, 15},
{-15, FFS(kNtIdlePriorityClass), kNtThreadPriorityTimeCritical, 15},
{-13, FFS(kNtHighPriorityClass), kNtThreadPriorityAboveNormal, 14},
{-11, FFS(kNtHighPriorityClass), kNtThreadPriorityNormal, 13},
{-9, FFS(kNtHighPriorityClass), kNtThreadPriorityBelowNormal, 12},
{-7, FFS(kNtNormalPriorityClass), kNtThreadPriorityHighest, 11},
{-5, FFS(kNtHighPriorityClass), kNtThreadPriorityLowest, 11},
{-3, FFS(kNtNormalPriorityClass), kNtThreadPriorityAboveNormal, 10},
{-1, FFS(kNtNormalPriorityClass), kNtThreadPriorityHighest, 9},
{0, FFS(kNtNormalPriorityClass), kNtThreadPriorityNormal, 9},
{1, FFS(kNtNormalPriorityClass), kNtThreadPriorityAboveNormal, 8},
{2, FFS(kNtNormalPriorityClass), kNtThreadPriorityBelowNormal, 8},
{3, FFS(kNtNormalPriorityClass), kNtThreadPriorityNormal, 7},
{4, FFS(kNtNormalPriorityClass), kNtThreadPriorityLowest, 7},
{5, FFS(kNtIdlePriorityClass), kNtThreadPriorityHighest, 6},
{6, FFS(kNtNormalPriorityClass), kNtThreadPriorityBelowNormal, 6},
{7, FFS(kNtIdlePriorityClass), kNtThreadPriorityAboveNormal, 5},
{9, FFS(kNtNormalPriorityClass), kNtThreadPriorityLowest, 5},
{11, FFS(kNtIdlePriorityClass), kNtThreadPriorityNormal, 4},
{13, FFS(kNtIdlePriorityClass), kNtThreadPriorityBelowNormal, 3},
{15, FFS(kNtIdlePriorityClass), kNtThreadPriorityLowest, 2},
{17, FFS(kNtHighPriorityClass), kNtThreadPriorityIdle, 1},
{18, FFS(kNtNormalPriorityClass), kNtThreadPriorityIdle, 1},
{19, FFS(kNtIdlePriorityClass), kNtThreadPriorityIdle, 1},
{-20, ffs(kNtHighPriorityClass), kNtThreadPriorityHighest, 15},
{-18, ffs(kNtHighPriorityClass), kNtThreadPriorityTimeCritical, 15},
{-17, ffs(kNtNormalPriorityClass), kNtThreadPriorityTimeCritical, 15},
{-15, ffs(kNtIdlePriorityClass), kNtThreadPriorityTimeCritical, 15},
{-13, ffs(kNtHighPriorityClass), kNtThreadPriorityAboveNormal, 14},
{-11, ffs(kNtHighPriorityClass), kNtThreadPriorityNormal, 13},
{-9, ffs(kNtHighPriorityClass), kNtThreadPriorityBelowNormal, 12},
{-7, ffs(kNtNormalPriorityClass), kNtThreadPriorityHighest, 11},
{-5, ffs(kNtHighPriorityClass), kNtThreadPriorityLowest, 11},
{-3, ffs(kNtNormalPriorityClass), kNtThreadPriorityAboveNormal, 10},
{-1, ffs(kNtNormalPriorityClass), kNtThreadPriorityHighest, 9},
{0, ffs(kNtNormalPriorityClass), kNtThreadPriorityNormal, 9},
{1, ffs(kNtNormalPriorityClass), kNtThreadPriorityAboveNormal, 8},
{2, ffs(kNtNormalPriorityClass), kNtThreadPriorityBelowNormal, 8},
{3, ffs(kNtNormalPriorityClass), kNtThreadPriorityNormal, 7},
{4, ffs(kNtNormalPriorityClass), kNtThreadPriorityLowest, 7},
{5, ffs(kNtIdlePriorityClass), kNtThreadPriorityHighest, 6},
{6, ffs(kNtNormalPriorityClass), kNtThreadPriorityBelowNormal, 6},
{7, ffs(kNtIdlePriorityClass), kNtThreadPriorityAboveNormal, 5},
{9, ffs(kNtNormalPriorityClass), kNtThreadPriorityLowest, 5},
{11, ffs(kNtIdlePriorityClass), kNtThreadPriorityNormal, 4},
{13, ffs(kNtIdlePriorityClass), kNtThreadPriorityBelowNormal, 3},
{15, ffs(kNtIdlePriorityClass), kNtThreadPriorityLowest, 2},
{17, ffs(kNtHighPriorityClass), kNtThreadPriorityIdle, 1},
{18, ffs(kNtNormalPriorityClass), kNtThreadPriorityIdle, 1},
{19, ffs(kNtIdlePriorityClass), kNtThreadPriorityIdle, 1},
};
const unsigned kNtPriorityCombosLen = ARRAYLEN(kNtPriorityCombos);

16
libc/calls/readansi.c
View file

@ -29,11 +29,11 @@
* how long each sequence is, so that each read consumes a single thing
* from the underlying file descriptor, e.g.
*
* "a" ALFA
* "\316\261" ALPHA
* "\033[A" CURSOR UP
* "\033[38;5;202m" ORANGERED
* "\eOP" PF1
* "a" ALFA
* "\316\261" ALPHA
* "\033[A" CURSOR UP
* "\033[38;5;202m" ORANGERED
* "\eOP" PF1
*
* This routine generalizes to ascii, utf-8, chorded modifier keys,
* function keys, color codes, c0/c1 control codes, cursor movement,
@ -48,9 +48,9 @@
* tokenized as a single read. Lastly note, this function has limited
* support for UNICODE representations of C0/C1 control codes, e.g.
*
* "\000" NUL
* "\300\200" NUL
* "\302\233A" CURSOR UP
* "\000" NUL
* "\300\200" NUL
* "\302\233A" CURSOR UP
*
* @param buf is guaranteed to receive a NUL terminator if size>0
* @return number of bytes read (helps differentiate "\0" vs. "")

31
libc/calls/setitimer.c
View file

@ -28,27 +28,28 @@
*
* Raise SIGALRM every 1.5s:
*
* CHECK_NE(-1, sigaction(SIGALRM,
* &(struct sigaction){.sa_sigaction = missingno},
* NULL));
* CHECK_NE(-1, setitimer(ITIMER_REAL,
* &(const struct itimerval){{1, 500000}, {1, 500000}},
* NULL));
* CHECK_NE(-1, sigaction(SIGALRM,
* &(struct sigaction){.sa_sigaction = missingno},
* NULL));
* CHECK_NE(-1, setitimer(ITIMER_REAL,
* &(const struct itimerval){{1, 500000},
* {1, 500000}},
* NULL));
*
* Set single-shot 50ms timer callback to interrupt laggy connect():
*
* CHECK_NE(-1, sigaction(SIGALRM,
* &(struct sigaction){.sa_sigaction = missingno,
* .sa_flags = SA_RESETHAND},
* NULL));
* CHECK_NE(-1, setitimer(ITIMER_REAL,
* &(const struct itimerval){{0, 0}, {0, 50000}},
* NULL));
* if (connect(...) == -1 && errno == EINTR) { ... }
* CHECK_NE(-1, sigaction(SIGALRM,
* &(struct sigaction){.sa_sigaction = missingno,
* .sa_flags = SA_RESETHAND},
* NULL));
* CHECK_NE(-1, setitimer(ITIMER_REAL,
* &(const struct itimerval){{0, 0}, {0, 50000}},
* NULL));
* if (connect(...) == -1 && errno == EINTR) { ... }
*
* Disarm timer:
*
* CHECK_NE(-1, setitimer(ITIMER_REAL, &(const struct itimerval){0}, NULL));
* CHECK_NE(-1, setitimer(ITIMER_REAL, &(const struct itimerval){0}, NULL));
*
* Be sure to check for EINTR on your i/o calls, for best low latency.
*

8
libc/calls/sigaction.c
View file

@ -112,10 +112,10 @@ static void sigaction$native2cosmo(union metasigaction *sa) {
/**
* Installs handler for kernel interrupt, e.g.:
*
* void GotCtrlC(int sig, siginfo_t *si, ucontext_t *ctx);
* struct sigaction sa = {.sa_sigaction = GotCtrlC,
* .sa_flags = SA_RESETHAND|SA_RESTART|SA_SIGINFO};
* CHECK_NE(-1, sigaction(SIGINT, &sa, NULL));
* void GotCtrlC(int sig, siginfo_t *si, ucontext_t *ctx);
* struct sigaction sa = {.sa_sigaction = GotCtrlC,
* .sa_flags = SA_RESETHAND|SA_RESTART|SA_SIGINFO};
* CHECK_NE(-1, sigaction(SIGINT, &sa, NULL));
*
* @see xsigaction() for a much better api
* @asyncsignalsafe

6
libc/calls/sigprocmask.c
View file

@ -26,9 +26,9 @@
/**
* Changes program signal blocking state, e.g.:
*
* sigset_t oldmask;
* sigprocmask(SIG_BLOCK, &kSigsetFull, &oldmask);
* sigprocmask(SIG_SETMASK, &oldmask, NULL);
* sigset_t oldmask;
* sigprocmask(SIG_BLOCK, &kSigsetFull, &oldmask);
* sigprocmask(SIG_SETMASK, &oldmask, NULL);
*
* @param how can be SIG_BLOCK (U), SIG_UNBLOCK (/), SIG_SETMASK (=)
* @param set is the new mask content (optional)