LibC: Add POSIX spec comments for stdio APIs

1 files changed, 56 insertions, 0 deletions

diff --git a/Userland/Libraries/LibC/stdio.cpp b/Userland/Libraries/LibC/stdio.cpp
index a5ce5a5528..73fde4db7c 100644
--- a/Userland/Libraries/LibC/stdio.cpp
+++ b/Userland/Libraries/LibC/stdio.cpp
@@ -523,6 +523,7 @@ void __stdio_init()
     __stdio_is_initialized = true;
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/setvbuf.html
 int setvbuf(FILE* stream, char* buf, int mode, size_t size)
 {
     VERIFY(stream);
@@ -535,6 +536,7 @@ int setvbuf(FILE* stream, char* buf, int mode, size_t size)
     return 0;
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/setbuf.html
 void setbuf(FILE* stream, char* buf)
 {
     setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ);
@@ -545,6 +547,7 @@ void setlinebuf(FILE* stream)
     setvbuf(stream, nullptr, _IOLBF, 0);
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/fileno.html
 int fileno(FILE* stream)
 {
     VERIFY(stream);
@@ -552,6 +555,7 @@ int fileno(FILE* stream)
     return stream->fileno();
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/feof.html
 int feof(FILE* stream)
 {
     VERIFY(stream);
@@ -559,6 +563,7 @@ int feof(FILE* stream)
     return stream->eof();
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/fflush.html
 int fflush(FILE* stream)
 {
     if (!stream) {
@@ -569,6 +574,7 @@ int fflush(FILE* stream)
     return stream->flush() ? 0 : EOF;
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/fgets.html
 char* fgets(char* buffer, int size, FILE* stream)
 {
     VERIFY(stream);
@@ -577,6 +583,7 @@ char* fgets(char* buffer, int size, FILE* stream)
     return ok ? buffer : nullptr;
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/fgetc.html
 int fgetc(FILE* stream)
 {
     VERIFY(stream);
@@ -597,6 +604,7 @@ int fgetc_unlocked(FILE* stream)
     return EOF;
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/getc.html
 int getc(FILE* stream)
 {
     return fgetc(stream);
@@ -607,11 +615,13 @@ int getc_unlocked(FILE* stream)
     return fgetc_unlocked(stream);
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/getchar.html
 int getchar()
 {
     return getc(stdin);
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/getdelim.html
 ssize_t getdelim(char** lineptr, size_t* n, int delim, FILE* stream)
 {
     if (!lineptr || !n) {
@@ -658,11 +668,13 @@ ssize_t getdelim(char** lineptr, size_t* n, int delim, FILE* stream)
     }
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/getline.html
 ssize_t getline(char** lineptr, size_t* n, FILE* stream)
 {
     return getdelim(lineptr, n, '\n', stream);
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/ungetc.html
 int ungetc(int c, FILE* stream)
 {
     VERIFY(stream);
@@ -671,6 +683,7 @@ int ungetc(int c, FILE* stream)
     return ok ? c : EOF;
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/fputc.html
 int fputc(int ch, FILE* stream)
 {
     VERIFY(stream);
@@ -683,16 +696,19 @@ int fputc(int ch, FILE* stream)
     return byte;
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/putc.html
 int putc(int ch, FILE* stream)
 {
     return fputc(ch, stream);
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/putchar.html
 int putchar(int ch)
 {
     return putc(ch, stdout);
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/fputs.html
 int fputs(const char* s, FILE* stream)
 {
     VERIFY(stream);
@@ -704,6 +720,7 @@ int fputs(const char* s, FILE* stream)
     return 1;
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/puts.html
 int puts(const char* s)
 {
     int rc = fputs(s, stdout);
@@ -712,6 +729,7 @@ int puts(const char* s)
     return fputc('\n', stdout);
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/clearerr.html
 void clearerr(FILE* stream)
 {
     VERIFY(stream);
@@ -719,6 +737,7 @@ void clearerr(FILE* stream)
     stream->clear_err();
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/ferror.html
 int ferror(FILE* stream)
 {
     VERIFY(stream);
@@ -737,6 +756,7 @@ size_t fread_unlocked(void* ptr, size_t size, size_t nmemb, FILE* stream)
     return nread / size;
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/fread.html
 size_t fread(void* ptr, size_t size, size_t nmemb, FILE* stream)
 {
     VERIFY(stream);
@@ -744,6 +764,7 @@ size_t fread(void* ptr, size_t size, size_t nmemb, FILE* stream)
     return fread_unlocked(ptr, size, nmemb, stream);
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/fwrite.html
 size_t fwrite(const void* ptr, size_t size, size_t nmemb, FILE* stream)
 {
     VERIFY(stream);
@@ -756,6 +777,7 @@ size_t fwrite(const void* ptr, size_t size, size_t nmemb, FILE* stream)
     return nwritten / size;
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/fseek.html
 int fseek(FILE* stream, long offset, int whence)
 {
     VERIFY(stream);
@@ -763,6 +785,7 @@ int fseek(FILE* stream, long offset, int whence)
     return stream->seek(offset, whence);
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/fseeko.html
 int fseeko(FILE* stream, off_t offset, int whence)
 {
     VERIFY(stream);
@@ -770,6 +793,7 @@ int fseeko(FILE* stream, off_t offset, int whence)
     return stream->seek(offset, whence);
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/ftell.html
 long ftell(FILE* stream)
 {
     VERIFY(stream);
@@ -777,6 +801,7 @@ long ftell(FILE* stream)
     return stream->tell();
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/ftello.html
 off_t ftello(FILE* stream)
 {
     VERIFY(stream);
@@ -784,6 +809,7 @@ off_t ftello(FILE* stream)
     return stream->tell();
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/fgetpos.html
 int fgetpos(FILE* stream, fpos_t* pos)
 {
     VERIFY(stream);
@@ -798,6 +824,7 @@ int fgetpos(FILE* stream, fpos_t* pos)
     return 0;
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/fsetpos.html
 int fsetpos(FILE* stream, const fpos_t* pos)
 {
     VERIFY(stream);
@@ -807,6 +834,7 @@ int fsetpos(FILE* stream, const fpos_t* pos)
     return stream->seek(*pos, SEEK_SET);
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/rewind.html
 void rewind(FILE* stream)
 {
     fseek(stream, 0, SEEK_SET);
@@ -824,12 +852,14 @@ ALWAYS_INLINE static void stream_putch(char*&, char ch)
     fputc(ch, __current_stream);
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/vfprintf.html
 int vfprintf(FILE* stream, const char* fmt, va_list ap)
 {
     __current_stream = stream;
     return printf_internal(stream_putch, nullptr, fmt, ap);
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/fprintf.html
 int fprintf(FILE* stream, const char* fmt, ...)
 {
     va_list ap;
@@ -839,11 +869,13 @@ int fprintf(FILE* stream, const char* fmt, ...)
     return ret;
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/vprintf.html
 int vprintf(const char* fmt, va_list ap)
 {
     return printf_internal(stdout_putch, nullptr, fmt, ap);
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/printf.html
 int printf(const char* fmt, ...)
 {
     va_list ap;
@@ -853,6 +885,7 @@ int printf(const char* fmt, ...)
     return ret;
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/vasprintf.html
 int vasprintf(char** strp, const char* fmt, va_list ap)
 {
     StringBuilder builder;
@@ -863,6 +896,7 @@ int vasprintf(char** strp, const char* fmt, va_list ap)
     return length;
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/asprintf.html
 int asprintf(char** strp, const char* fmt, ...)
 {
     StringBuilder builder;
@@ -881,6 +915,7 @@ static void buffer_putch(char*& bufptr, char ch)
     *bufptr++ = ch;
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/vsprintf.html
 int vsprintf(char* buffer, const char* fmt, va_list ap)
 {
     int ret = printf_internal(buffer_putch, buffer, fmt, ap);
@@ -888,6 +923,7 @@ int vsprintf(char* buffer, const char* fmt, va_list ap)
     return ret;
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/sprintf.html
 int sprintf(char* buffer, const char* fmt, ...)
 {
     va_list ap;
@@ -906,6 +942,7 @@ ALWAYS_INLINE void sized_buffer_putch(char*& bufptr, char ch)
     }
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/vsnprintf.html
 int vsnprintf(char* buffer, size_t size, const char* fmt, va_list ap)
 {
     if (size) {
@@ -922,6 +959,7 @@ int vsnprintf(char* buffer, size_t size, const char* fmt, va_list ap)
     return ret;
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/snprintf.html
 int snprintf(char* buffer, size_t size, const char* fmt, ...)
 {
     va_list ap;
@@ -931,6 +969,7 @@ int snprintf(char* buffer, size_t size, const char* fmt, ...)
     return ret;
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/perror.html
 void perror(const char* s)
 {
     int saved_errno = errno;
@@ -975,6 +1014,7 @@ static int parse_mode(const char* mode)
     return flags;
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/fopen.html
 FILE* fopen(const char* pathname, const char* mode)
 {
     int flags = parse_mode(mode);
@@ -984,6 +1024,7 @@ FILE* fopen(const char* pathname, const char* mode)
     return FILE::create(fd, flags);
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/freopen.html
 FILE* freopen(const char* pathname, const char* mode, FILE* stream)
 {
     VERIFY(stream);
@@ -1001,6 +1042,7 @@ FILE* freopen(const char* pathname, const char* mode, FILE* stream)
     return stream;
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/fdopen.html
 FILE* fdopen(int fd, const char* mode)
 {
     int flags = parse_mode(mode);
@@ -1015,6 +1057,7 @@ static inline bool is_default_stream(FILE* stream)
     return stream == stdin || stream == stdout || stream == stderr;
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/fclose.html
 int fclose(FILE* stream)
 {
     VERIFY(stream);
@@ -1033,6 +1076,7 @@ int fclose(FILE* stream)
     return ok ? 0 : EOF;
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/rename.html
 int rename(const char* oldpath, const char* newpath)
 {
     if (!oldpath || !newpath) {
@@ -1049,12 +1093,14 @@ void dbgputstr(const char* characters, size_t length)
     syscall(SC_dbgputstr, characters, length);
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/tmpnam.html
 char* tmpnam(char*)
 {
     dbgln("FIXME: Implement tmpnam()");
     TODO();
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/popen.html
 FILE* popen(const char* command, const char* type)
 {
     if (!type || (*type != 'r' && *type != 'w')) {
@@ -1112,6 +1158,7 @@ FILE* popen(const char* command, const char* type)
     return file;
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/pclose.html
 int pclose(FILE* stream)
 {
     VERIFY(stream);
@@ -1124,6 +1171,7 @@ int pclose(FILE* stream)
     return wstatus;
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/remove.html
 int remove(const char* pathname)
 {
     if (unlink(pathname) < 0) {
@@ -1134,6 +1182,7 @@ int remove(const char* pathname)
     return 0;
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/scanf.html
 int scanf(const char* fmt, ...)
 {
     va_list ap;
@@ -1143,6 +1192,7 @@ int scanf(const char* fmt, ...)
     return count;
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/fscanf.html
 int fscanf(FILE* stream, const char* fmt, ...)
 {
     va_list ap;
@@ -1152,6 +1202,7 @@ int fscanf(FILE* stream, const char* fmt, ...)
     return count;
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/sscanf.html
 int sscanf(const char* buffer, const char* fmt, ...)
 {
     va_list ap;
@@ -1161,6 +1212,7 @@ int sscanf(const char* buffer, const char* fmt, ...)
     return count;
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/vfscanf.html
 int vfscanf(FILE* stream, const char* fmt, va_list ap)
 {
     char buffer[BUFSIZ];
@@ -1169,21 +1221,25 @@ int vfscanf(FILE* stream, const char* fmt, va_list ap)
     return vsscanf(buffer, fmt, ap);
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/vscanf.html
 int vscanf(const char* fmt, va_list ap)
 {
     return vfscanf(stdin, fmt, ap);
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/flockfile.html
 void flockfile([[maybe_unused]] FILE* filehandle)
 {
     dbgln("FIXME: Implement flockfile()");
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/funlockfile.html
 void funlockfile([[maybe_unused]] FILE* filehandle)
 {
     dbgln("FIXME: Implement funlockfile()");
 }
 
+// https://pubs.opengroup.org/onlinepubs/9699919799/functions/tmpfile.html
 FILE* tmpfile()
 {
     char tmp_path[] = "/tmp/XXXXXX";