From 367a2ce5216f7c45638736c65986add05273e645 Mon Sep 17 00:00:00 2001 From: apio Date: Fri, 6 Jan 2023 20:02:07 +0100 Subject: [PATCH] libc: header documentation for supported functions --- libc/include/errno.h | 3 +++ libc/include/stdio.h | 5 ++++- libc/include/stdlib.h | 30 +++++++++++++++--------------- libc/include/string.h | 20 ++++++++++++++++++++ libc/include/unistd.h | 8 +++++++- 5 files changed, 49 insertions(+), 17 deletions(-) diff --git a/libc/include/errno.h b/libc/include/errno.h index 5ffee032..fa751e89 100644 --- a/libc/include/errno.h +++ b/libc/include/errno.h @@ -1,6 +1,9 @@ +/* errno.h: Error management header. */ + #ifndef _ERRNO_H #define _ERRNO_H +/* The last error encountered after a call to a system or library function. */ extern int errno; #include diff --git a/libc/include/stdio.h b/libc/include/stdio.h index 422efb68..f99fc754 100644 --- a/libc/include/stdio.h +++ b/libc/include/stdio.h @@ -1,3 +1,5 @@ +/* stdio.h: Standard input/output header. */ + #ifndef _STDIO_H #define _STDIO_H @@ -36,7 +38,8 @@ extern "C" int vfprintf(FILE*, const char*, va_list); int sprintf(char*, const char*, ...); - int console_print(const char*); + /* Output a message to the console. */ + int console_print(const char* msg); #ifdef __cplusplus } diff --git a/libc/include/stdlib.h b/libc/include/stdlib.h index 736c2f93..38cb7095 100644 --- a/libc/include/stdlib.h +++ b/libc/include/stdlib.h @@ -32,22 +32,22 @@ extern "C" { #endif - /* Returns the absolute value of v. */ + /* Return the absolute value of an integer. */ int abs(int v); - /* Returns the absolute value of v. */ + /* Return the absolute value of a long integer. */ long labs(long v); - /* Returns the absolute value of v. */ + /* Return the absolute value of a long long integer. */ long long llabs(long long v); - /* Returns the result of dividing num by den, including the remainder. */ + /* Return the result of dividing two integers, including the remainder. */ div_t div(int num, int den); - /* Returns the result of dividing num by den, including the remainder. */ + /* Return the result of dividing two long integers, including the remainder. */ ldiv_t ldiv(long, long); - /* Returns the result of dividing num by den, including the remainder. */ + /* Return the result of dividing two long long integers, including the remainder. */ lldiv_t lldiv(long long, long long); void* malloc(size_t); @@ -55,40 +55,40 @@ extern "C" void* realloc(void*, size_t); void free(void*); - /* Aborts the program without performing any normal cleanup. */ + /* Abort the program without performing any normal cleanup. */ __noreturn void abort(); - /* Registers a handler to be run at normal program termination. */ + /* Register a handler to be run at normal program termination. */ int atexit(void (*func)(void)); - /* Parses a decimal integer from the provided string. */ + /* Parse a decimal integer from the a string. */ int atoi(const char* s); - /* Parses a decimal integer from the provided string. */ + /* Parse a decimal integer from the a string. */ long atol(const char* s); - /* Parses a decimal integer from the provided string. */ + /* Parse a decimal integer from the a string. */ long long atoll(const char* s); double atof(const char*); double strtod(const char*, char**); - /* Parses an integer of the specified base from the string str, storing the first non-number character in endptr if + /* Parse an integer of the specified base from a string, storing the first non-number character in endptr if * nonnull. */ long strtol(const char* str, char** endptr, int base); - /* Parses an unsigned integer of the specified base from the string str, storing the first non-number character in + /* Parse an unsigned integer of the specified base from a string, storing the first non-number character in * endptr if nonnull. */ unsigned long strtoul(const char* str, char** endptr, int base); int rand(); void srand(int); - /* Exits the program normally, performing any registered cleanup actions. */ + /* Exit the program normally, performing any registered cleanup actions. */ __noreturn void exit(int); - /* Exits the program abnormally, without performing any registered cleanup actions. */ + /* Exit the program abnormally, without performing any registered cleanup actions. */ __noreturn void _Exit(int); int system(const char*); diff --git a/libc/include/string.h b/libc/include/string.h index 7fd223ae..c2c59102 100644 --- a/libc/include/string.h +++ b/libc/include/string.h @@ -1,3 +1,5 @@ +/* string.h: String manipulation header. */ + #ifndef _STRING_H #define _STRING_H @@ -9,19 +11,37 @@ extern "C" { #endif + /* Copy n bytes of memory from src to dest. */ void* memcpy(void* dest, const void* src, size_t n); + + /* Set n bytes of memory to the character c. */ void* memset(void* buf, int c, size_t n); + + /* Compare n bytes of two memory locations. */ int memcmp(const void* a, const void* b, size_t n); + + /* Copy n bytes of memory from src to dest, where src and dest may overlap. */ void* memmove(void* dest, const void* src, size_t n); + + /* Return the length of a null-terminated string. */ size_t strlen(const char* str); + /* Compare two null-terminated strings. */ int strcmp(const char* a, const char* b); + + /* Copy the null-terminated string src into dest. Should be avoided to prevent buffer overflow attacks. */ __deprecated char* strcpy(char* dest, const char* src); + + /* Concatenate the null-terminated string src onto dest. Should be avoided to prevent buffer overflow attacks. */ __deprecated char* strcat(char* dest, const char* src); + + /* Return a pointer to the first occurrence of the character c in str, or NULL if it could not be found. */ char* strchr(const char* str, int c); + /* Return a heap-allocated copy of a string. */ char* strdup(const char* str); + /* Return the human-readable description of an error number. */ char* strerror(int errnum); #ifdef __cplusplus diff --git a/libc/include/unistd.h b/libc/include/unistd.h index 46e904c2..218be84d 100644 --- a/libc/include/unistd.h +++ b/libc/include/unistd.h @@ -1,6 +1,11 @@ +/* unistd.h: POSIX constants and functions. */ + #ifndef _UNISTD_H #define _UNISTD_H +#define __need_NULL +#include + #include #include @@ -16,7 +21,8 @@ extern "C" int execve(const char*, char* const*, char* const*); int execvp(const char*, char* const*); - long syscall(long, ...); + /* Calls the operating system kernel for a specific service. */ + long syscall(long num, ...); #ifdef __cplusplus }