Improve documentation

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

View file

@ -30,6 +30,7 @@
* @param mode can be R_OK, W_OK, X_OK, F_OK
* @return 0 if ok, or -1 and sets errno
* @asyncsignalsafe
* @syscall
*/
int access(const char *path, int mode) {
char16_t path16[PATH_MAX];

View file

@ -25,6 +25,7 @@
/**
* Sets current directory.
* @asyncsignalsafe
* @syscall
*/
int chdir(const char *path) {
if (!path) return efault();

View file

@ -26,15 +26,15 @@
/**
* 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));
* 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
* 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 ;-)
*
@ -43,6 +43,7 @@
* @errors ENOENT, ENOTDIR, ENOSYS
* @asyncsignalsafe
* @see fchmod()
* @syscall
*/
int chmod(const char *pathname, uint32_t mode) {
if (!pathname) return efault();

View file

@ -33,6 +33,7 @@
* @see /etc/passwd for user ids
* @see /etc/group for group ids
* @asyncsignalsafe
* @syscall
*/
int chown(const char *pathname, uint32_t uid, uint32_t gid) {
if (!pathname) return efault();

View file

@ -25,6 +25,7 @@
* Returns how much CPU program has consumed on time-sharing system.
*
* @return value that can be divided by CLOCKS_PER_SEC, or -1 w/ errno
* @see clock_gettime()
*/
int64_t clock(void) {
struct timespec ts;

View file

@ -18,7 +18,7 @@
02110-1301 USA
*/
#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/timespec.h"
@ -51,6 +51,7 @@
* errno isn't restored to its original value, to detect prec. loss
* @see strftime(), gettimeofday()
* @asyncsignalsafe
* @syscall
*/
int clock_gettime(int clockid, struct timespec *out_ts) {
/* TODO(jart): Just ignore O/S for MONOTONIC and measure RDTSC on start */

View file

@ -28,8 +28,12 @@
/**
* Closes file descriptor.
*
* This function may be used for file descriptors returned by socket,
* accept, epoll_create, and zipos file descriptors too.
*
* @return 0 on success, or -1 w/ errno
* @asyncsignalsafe
* @syscall
*/
int close(int fd) {
int rc;

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/calls/calls.h"
#include "libc/dce.h"
#include "libc/errno.h"

View file

@ -19,7 +19,7 @@
*/
#include "libc/assert.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/errno.h"

View file

@ -23,12 +23,16 @@
/**
* Creates new file, returning open()'d file descriptor.
*
* This function is shorthand for:
*
* open(file, O_CREAT | O_WRONLY | O_TRUNC, mode)
*
* @param file is a UTF-8 string, which is truncated if it exists
* @param mode is an octal user/group/other permission, e.g. 0755
* @return a number registered with the system to track the open file,
* which must be stored using a 64-bit type in order to support both
* System V and Windows, and must be closed later on using close()
* @see touch()
* @see open(), touch()
* @asyncsignalsafe
*/
nodiscard int creat(const char *file, uint32_t mode) {

View file

@ -20,7 +20,7 @@
#include "libc/calls/calls.h"
/**
* Formats string directly to system i/o device.
* Formats string directly to file descriptor.
*/
int(dprintf)(int fd, const char *fmt, ...) {
int rc;

View file

@ -43,8 +43,8 @@ textwindows int dup$nt(int oldfd, int newfd, int flags) {
return -1;
}
if (DuplicateHandle(GetCurrentProcess(), g_fds.p[oldfd].handle,
GetCurrentProcess(), &g_fds.p[newfd].handle, 0,
flags & O_CLOEXEC, kNtDuplicateSameAccess)) {
GetCurrentProcess(), &g_fds.p[newfd].handle, 0, true,
kNtDuplicateSameAccess)) {
g_fds.p[newfd].kind = g_fds.p[oldfd].kind;
g_fds.p[newfd].flags = flags;
return newfd;

View file

@ -27,6 +27,7 @@
* @param fd remains open afterwards
* @return some arbitrary new number for fd
* @asyncsignalsafe
* @syscall
*/
nodiscard int dup(int fd) {
if (!IsWindows()) {

View file

@ -29,6 +29,7 @@
* unless it's equal to oldfd, in which case dup2() is a no-op
* @return new file descriptor, or -1 w/ errno
* @asyncsignalsafe
* @syscall
*/
int dup2(int oldfd, int newfd) {
if (oldfd == newfd) return newfd;

View file

@ -33,6 +33,8 @@
* @param newfd if already assigned, is silently closed beforehand;
* unless it's equal to oldfd, in which case dup2() is a no-op
* @flags can have O_CLOEXEC
* @see dup(), dup2()
* @syscall
*/
int dup3(int oldfd, int newfd, int flags) {
if (oldfd == newfd) return einval();

View file

@ -32,6 +32,7 @@
* @param flags can be R_OK, W_OK, X_OK, F_OK
* @return 0 if ok, or -1 and sets errno
* @asyncsignalsafe
* @syscall
*/
int faccessat(int dirfd, const char *path, int mode, uint32_t flags) {
if (!path) return efault();

View file

@ -30,6 +30,7 @@
* @param len 0 means til end of file
* @param advice can be MADV_SEQUENTIAL, MADV_RANDOM, etc.
* @return -1 on error
* @syscall
*/
int fadvise(int fd, uint64_t offset, uint64_t len, int advice) {
if (!IsWindows()) {

View file

@ -38,6 +38,7 @@
* @param length is how much physical space to reserve / commit
* @return 0 on success, or -1 w/ errno
* @see ftruncate()
* @syscall
*/
int fallocate(int fd, int32_t mode, int64_t offset, int64_t length) {
int rc;

View file

@ -41,6 +41,7 @@
* @errors ENOSYS
* @asyncsignalsafe
* @see chmod()
* @syscall
*/
int fchmod(int fd, uint32_t mode) {
/* TODO(jart): Windows */

View file

@ -29,6 +29,7 @@
* @return 0 on success, or -1 w/ errno
* @see /etc/passwd for user ids
* @see /etc/group for group ids
* @syscall
*/
int fchown(int fd, uint32_t uid, uint32_t gid) {
/* TODO(jart): Windows? */

View file

@ -32,6 +32,7 @@
* @see /etc/passwd for user ids
* @see /etc/group for group ids
* @asyncsignalsafe
* @syscall
*/
int fchownat(int dirfd, const char *pathname, uint32_t uid, uint32_t gid,
uint32_t flags) {

View file

@ -30,6 +30,7 @@
* @param arg can be FD_CLOEXEC, etc. depending
* @return 0 on success, or -1 w/ errno
* @asyncsignalsafe
* @syscall
*/
int fcntl(int fd, int cmd, ...) {
va_list va;

View file

@ -27,6 +27,7 @@
* @return 0 on success, or -1 w/ errno
* @see fsync(), sync_file_range()
* @asyncsignalsafe
* @syscall
*/
int fdatasync(int fd) {
if (!IsWindows()) {

View file

@ -1,28 +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/calls/internal.h"
enum FdKind fdkind(int fd) {
if (0 <= fd && fd <= g_fds.n) {
return g_fds.p[fd].kind;
} else {
return kFdEmpty;
}
}

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/calls/internal.h"
#include "libc/calls/struct/stat.h"
#include "libc/fmt/conv.h"

View file

@ -25,9 +25,9 @@
STATIC_YOINK("_init_g_fds");
struct Fds g_fds;
hidden struct Fds g_fds;
void InitializeFileDescriptors(void) {
hidden void InitializeFileDescriptors(void) {
struct Fds *fds;
fds = VEIL("r", &g_fds);
pushmov(&fds->f, 3ul);

View file

@ -21,10 +21,6 @@
#include "libc/nt/startupinfo.h"
#include "libc/nt/struct/startupinfo.h"
/**
* GetStartupInfo() singleton.
* @see libc/runtime/winmain.c
*/
struct NtStartupInfo g_ntstartupinfo;
hidden struct NtStartupInfo g_ntstartupinfo;
STATIC_YOINK("_init_g_ntstartupinfo");

View file

@ -21,10 +21,6 @@
#include "libc/nt/struct/systeminfo.h"
#include "libc/nt/systeminfo.h"
/**
* GetSystemInfo() singleton.
* @see libc/runtime/winmain.c
*/
struct NtSystemInfo g_ntsysteminfo;
hidden struct NtSystemInfo g_ntsysteminfo;
STATIC_YOINK("_init_g_ntsysteminfo");

View file

@ -19,4 +19,4 @@
*/
#include "libc/calls/internal.h"
int g_sighandrvas[NSIG];
hidden int g_sighandrvas[NSIG];

View file

@ -18,7 +18,7 @@
02110-1301 USA
*/
#include "libc/bits/bits.h"
#include "libc/bits/safemacros.internal.h"
#include "libc/bits/safemacros.h"
#include "libc/runtime/runtime.h"
#include "libc/str/str.h"

View file

@ -18,7 +18,7 @@
02110-1301 USA
*/
#include "libc/alg/alg.h"
#include "libc/bits/safemacros.internal.h"
#include "libc/bits/safemacros.h"
#include "libc/calls/calls.h"
#include "libc/errno.h"
#include "libc/str/str.h"

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/calls/calls.h"
#include "libc/mem/mem.h"
#include "libc/runtime/runtime.h"

View file

@ -20,7 +20,7 @@
#include "libc/alg/alg.h"
#include "libc/alg/arraylist.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/hefty/ntspawn.h"
#include "libc/calls/internal.h"

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/calls/calls.h"
#include "libc/mem/mem.h"
#include "libc/runtime/runtime.h"

View file

@ -68,7 +68,6 @@ hidden extern const struct NtSecurityAttributes kNtIsInheritable;
ssize_t __getemptyfd(void) hidden;
int __ensurefds(int) hidden;
void __removefd(int) hidden;
enum FdKind fdkind(int) hidden nosideeffect;
bool __isfdopen(int) hidden nosideeffect;
bool __isfdkind(int, enum FdKind) hidden nosideeffect;

View file

@ -18,7 +18,7 @@
02110-1301 USA
*/
#include "libc/alg/alg.h"
#include "libc/bits/safemacros.internal.h"
#include "libc/bits/safemacros.h"
#include "libc/calls/calls.h"
#include "libc/calls/internal.h"
#include "libc/dce.h"

View file

@ -19,4 +19,4 @@
*/
#include "libc/calls/internal.h"
const struct Fd kEmptyFd;
hidden const struct Fd kEmptyFd;

View file

@ -25,7 +25,7 @@
#include "libc/nt/enum/processcreationflags.h"
#include "libc/nt/enum/threadpriority.h"
const struct NtPriorityCombo kNtPriorityCombos[] = {
hidden const struct NtPriorityCombo kNtPriorityCombos[] = {
{-20, ffs(kNtHighPriorityClass), kNtThreadPriorityHighest, 15},
{-18, ffs(kNtHighPriorityClass), kNtThreadPriorityTimeCritical, 15},
{-17, ffs(kNtNormalPriorityClass), kNtThreadPriorityTimeCritical, 15},
@ -54,4 +54,4 @@ const struct NtPriorityCombo kNtPriorityCombos[] = {
{19, ffs(kNtIdlePriorityClass), kNtThreadPriorityIdle, 1},
};
const unsigned kNtPriorityCombosLen = ARRAYLEN(kNtPriorityCombos);
hidden const unsigned kNtPriorityCombosLen = ARRAYLEN(kNtPriorityCombos);

View file

@ -10,8 +10,8 @@ struct NtPriorityCombo {
int8_t prio;
};
extern const unsigned kNtPriorityCombosLen;
extern const struct NtPriorityCombo kNtPriorityCombos[];
hidden extern const unsigned kNtPriorityCombosLen;
hidden extern const struct NtPriorityCombo kNtPriorityCombos[];
COSMOPOLITAN_C_END_
#endif /* !(__ASSEMBLER__ + __LINKER__ + 0) */

View file

@ -26,6 +26,8 @@
#include "libc/nt/thunk/msabi.h"
#include "libc/sysv/consts/nr.h"
extern __msabi typeof(VirtualProtect) *const __imp_VirtualProtect;
/**
* Modifies restrictions on virtual memory address range.
*
@ -34,7 +36,6 @@
* @see mmap()
*/
int mprotect(void *addr, uint64_t len, int prot) {
extern __msabi typeof(VirtualProtect) *const __imp_VirtualProtect;
bool cf;
int64_t rc;
uint32_t oldprot;

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/calls/calls.h"
#include "libc/fmt/conv.h"
#include "libc/sysv/consts/prio.h"

View file

@ -19,7 +19,7 @@
*/
#include "libc/bits/bits.h"
#include "libc/bits/initializer.internal.h"
#include "libc/bits/safemacros.internal.h"
#include "libc/bits/safemacros.h"
#include "libc/calls/calls.h"
#include "libc/dce.h"
#include "libc/nexgen32e/rdtsc.h"

View file

@ -19,7 +19,7 @@
*/
#include "libc/calls/ntmagicpaths.internal.h"
const struct NtMagicPaths kNtMagicPaths = {
hidden const struct NtMagicPaths kNtMagicPaths = {
#define TAB(NAME, STRING) STRING,
#include "libc/calls/ntmagicpaths.inc"
#undef TAB

View file

@ -9,7 +9,7 @@ struct NtMagicPaths {
#undef TAB
};
extern const struct NtMagicPaths kNtMagicPaths;
hidden extern const struct NtMagicPaths kNtMagicPaths;
COSMOPOLITAN_C_END_
#endif /* !(__ASSEMBLER__ + __LINKER__ + 0) */

View file

@ -17,19 +17,21 @@
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301 USA
*/
#include "libc/calls/internal.h"
#include "libc/nt/privilege.h"
#include "libc/nt/struct/tokenprivileges.h"
#include "libc/calls/internal.h"
/**
* Sets NT permission thing, e.g.
*
* int64_t htoken;
* if (OpenProcessToken(GetCurrentProcess(),
* kNtTokenAdjustPrivileges | kNtTokenQuery, &htoken)) {
* ntsetprivilege(htoken, u"SeManageVolumePrivilege", kNtSePrivilegeEnabled);
* CloseHandle(htoken);
* }
* int64_t htoken;
* if (OpenProcessToken(GetCurrentProcess(),
* kNtTokenAdjustPrivileges | kNtTokenQuery,
* &htoken)) {
* ntsetprivilege(htoken, u"SeManageVolumePrivilege",
* kNtSePrivilegeEnabled);
* CloseHandle(htoken);
* }
*/
textwindows bool32 ntsetprivilege(int64_t token, const char16_t *name,
uint32_t attrs) {

View file

@ -18,7 +18,7 @@
02110-1301 USA
*/
#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/iovec.h"

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/calls/calls.h"
#include "libc/calls/internal.h"
#include "libc/calls/struct/iovec.h"

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/calls/calls.h"
#include "libc/calls/internal.h"
#include "libc/dce.h"

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/calls/internal.h"
#include "libc/calls/kntprioritycombos.internal.h"
#include "libc/nt/process.h"

View file

@ -18,7 +18,7 @@
02110-1301 USA
*/
#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/sysinfo.h"

View file

@ -1,7 +1,7 @@
#ifndef COSMOPOLITAN_LIBC_CALLS_TERMIOS_INTERNAL_H_
#define COSMOPOLITAN_LIBC_CALLS_TERMIOS_INTERNAL_H_
#ifndef __STRICT_ANSI__
#include "libc/bits/safemacros.internal.h"
#include "libc/bits/safemacros.h"
#include "libc/calls/struct/metatermios.internal.h"
#include "libc/calls/struct/termios.h"
#include "libc/str/str.h"

View file

@ -20,7 +20,7 @@
#include "libc/calls/internal.h"
#include "libc/nt/struct/securityattributes.h"
const struct NtSecurityAttributes kNtIsInheritable = {
hidden const struct NtSecurityAttributes kNtIsInheritable = {
sizeof(struct NtSecurityAttributes),
NULL,
true,