feat(stdio): FILE buffering core and stream I/O
This commit is contained in:
+296
@@ -0,0 +1,296 @@
|
||||
#ifndef VLIBC_STDIO_H
|
||||
#define VLIBC_STDIO_H
|
||||
|
||||
/*
|
||||
* vlibc — <stdio.h>.
|
||||
*
|
||||
* Buffered stream I/O (todo 15). The FILE object is opaque to consumers;
|
||||
* the layout lives in src/stdio/stdio_impl.h. stdin/stdout/stderr are
|
||||
* pre-wired streams over fds 0/1/2 and are initialized lazily on first
|
||||
* use. On Linux there is no text/binary distinction, so the 'b' mode
|
||||
* character is accepted and ignored.
|
||||
*
|
||||
* Buffering modes for setvbuf: _IOFBF (fully buffered), _IOLBF (line
|
||||
* buffered: flush on newline), _IONBF (unbuffered). A stream opened on a
|
||||
* terminal defaults to line buffering for stdout and full buffering for
|
||||
* stdin; stderr is always unbuffered.
|
||||
*
|
||||
* getc/putc/getchar/putchar are declared as functions (address-taking and
|
||||
* #undef work) and additionally defined as macros over fgetc/fputc; the
|
||||
* macro arguments are evaluated exactly once.
|
||||
*
|
||||
* Level 2 (muslmimic) adds tmpnam/ctermid/setbuffer/setlinebuf and the
|
||||
* fopen64 name alias (identical ABI on LP64).
|
||||
*/
|
||||
|
||||
#include <vlibc/features.h>
|
||||
|
||||
#include <stddef.h>
|
||||
#include <sys/types.h>
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
/*
|
||||
* The opaque stream object. The underlying struct tag is vlibc_FILE (see
|
||||
* src/stdio/stdio_impl.h); consumers only ever use FILE *.
|
||||
*/
|
||||
typedef struct vlibc_FILE FILE;
|
||||
|
||||
/* The three pre-wired standard streams (fds 0, 1, 2). */
|
||||
extern FILE *stdin;
|
||||
extern FILE *stdout;
|
||||
extern FILE *stderr;
|
||||
|
||||
/* End of file indicator for character functions. */
|
||||
#define EOF (-1)
|
||||
|
||||
/* Minimum number of simultaneously open files. */
|
||||
#define FOPEN_MAX 16
|
||||
|
||||
/* Default buffer size for setvbuf/setbuf. */
|
||||
#define BUFSIZ 8192
|
||||
|
||||
/* Maximum length of a path argument for stdio functions. */
|
||||
#define FILENAME_MAX 4096
|
||||
|
||||
/* Minimum number of distinct tmpnam-generated names. */
|
||||
#define TMP_MAX 238328
|
||||
|
||||
/* Buffer sizes for tmpnam and ctermid results. */
|
||||
#define L_tmpnam 20
|
||||
#define L_ctermid 9
|
||||
|
||||
/* Seek positions for fseek/fseeko. */
|
||||
#define SEEK_SET 0
|
||||
#define SEEK_CUR 1
|
||||
#define SEEK_END 2
|
||||
|
||||
/* setvbuf modes. */
|
||||
#define _IOFBF 0 // NOLINT(bugprone-reserved-identifier)
|
||||
#define _IOLBF 1 // NOLINT(bugprone-reserved-identifier)
|
||||
#define _IONBF 2 // NOLINT(bugprone-reserved-identifier)
|
||||
|
||||
/* Opaque file position type for fgetpos/fsetpos. */
|
||||
typedef off_t fpos_t;
|
||||
|
||||
/*
|
||||
* Open the file at path with the given mode. The mode is 'r', 'w', or 'a',
|
||||
* optionally followed by '+' (update: read and write), 'b' (ignored on
|
||||
* Linux), and/or 'x' (exclusive create, C11). Returns NULL with errno set
|
||||
* on failure.
|
||||
*/
|
||||
FILE *
|
||||
fopen(const char *restrict path, const char *restrict mode);
|
||||
|
||||
/*
|
||||
* Wrap an existing descriptor in a stream. The requested mode must be
|
||||
* compatible with the descriptor's access mode (basic check via fcntl).
|
||||
* The descriptor is not duplicated; fclose closes it.
|
||||
*/
|
||||
FILE *
|
||||
fdopen(int fd, const char *mode);
|
||||
|
||||
/*
|
||||
* Rebind stream to path. The old descriptor is flushed and closed first.
|
||||
* With path == NULL only the mode changes and the descriptor stays open.
|
||||
* Returns NULL with errno set on failure.
|
||||
*/
|
||||
FILE *
|
||||
freopen(const char *restrict path, const char *restrict mode, FILE *restrict stream);
|
||||
|
||||
/*
|
||||
* Flush pending output, close the descriptor, and release the stream.
|
||||
* Returns EOF if flushing or closing failed.
|
||||
*/
|
||||
int
|
||||
fclose(FILE *stream);
|
||||
|
||||
/*
|
||||
* Flush pending output of stream. fflush(NULL) flushes all open streams
|
||||
* with pending output. On a stream with no pending writes (read mode) the
|
||||
* unread buffered data is discarded and the position rewound; this never
|
||||
* corrupts the stream. Returns EOF on error.
|
||||
*/
|
||||
int
|
||||
fflush(FILE *stream);
|
||||
|
||||
/*
|
||||
* Set the buffer of stream to buf. buf == NULL selects unbuffered I/O;
|
||||
* otherwise the buffer is used with full buffering and BUFSIZ size. Must
|
||||
* be called before the first operation on the stream.
|
||||
*/
|
||||
void
|
||||
setbuf(FILE *restrict stream, char *restrict buf);
|
||||
|
||||
/*
|
||||
* Set the buffering mode of stream: _IOFBF, _IOLBF, or _IONBF. With
|
||||
* buf != NULL the caller supplies size bytes of storage; with buf == NULL
|
||||
* the buffer is allocated lazily on first use (size is then ignored,
|
||||
* except that _IONBF needs no buffer). Returns 0, or -1 with errno EINVAL
|
||||
* for an invalid mode or a non-NULL buf with size 0 (except _IONBF).
|
||||
*/
|
||||
int
|
||||
setvbuf(FILE *restrict stream, char *restrict buf, int mode, size_t size);
|
||||
|
||||
/*
|
||||
* Read up to size * nmemb bytes in items of size bytes each. Returns the
|
||||
* number of complete items read; fewer than nmemb means end of file or an
|
||||
* error (distinguishable via feof/ferror). size or nmemb zero returns 0
|
||||
* without touching the stream.
|
||||
*/
|
||||
size_t
|
||||
fread(void *restrict ptr, size_t size, size_t nmemb, FILE *restrict stream);
|
||||
|
||||
/*
|
||||
* Write size * nmemb bytes in items of size bytes each. Returns the number
|
||||
* of complete items written; fewer than nmemb means an error (see
|
||||
* ferror).
|
||||
*/
|
||||
size_t
|
||||
fwrite(const void *restrict ptr, size_t size, size_t nmemb, FILE *restrict stream);
|
||||
|
||||
/* Read the next character as unsigned char, or EOF. */
|
||||
int
|
||||
fgetc(FILE *stream);
|
||||
|
||||
/* Write c as unsigned char; returns it, or EOF on error. */
|
||||
int
|
||||
fputc(int c, FILE *stream);
|
||||
|
||||
/* Same as fgetc/fputc; also provided as macros (arguments evaluated once). */
|
||||
int
|
||||
getc(FILE *stream);
|
||||
|
||||
int
|
||||
putc(int c, FILE *stream);
|
||||
|
||||
int
|
||||
getchar(void);
|
||||
|
||||
int
|
||||
putchar(int c);
|
||||
|
||||
/*
|
||||
* Read at most n-1 characters into s, stopping after (and keeping) a
|
||||
* newline, then NUL-terminate. Returns s, or NULL if no character was read
|
||||
* (end of file or error).
|
||||
*/
|
||||
char *
|
||||
fgets(char *restrict s, int n, FILE *restrict stream);
|
||||
|
||||
/*
|
||||
* Write the NUL-terminated string s to stream (no trailing newline is
|
||||
* added). Returns a non-negative value, or EOF on error.
|
||||
*/
|
||||
int
|
||||
fputs(const char *restrict s, FILE *restrict stream);
|
||||
|
||||
/*
|
||||
* Push c back onto the input stream; the next read returns it again. One
|
||||
* byte of pushback is guaranteed. Returns c, or EOF on error (also for
|
||||
* ungetc(EOF)). A successful seek discards the pushed-back character.
|
||||
*/
|
||||
int
|
||||
ungetc(int c, FILE *stream);
|
||||
|
||||
/* Position the stream (see SEEK_SET/SEEK_CUR/SEEK_END); clears feof. */
|
||||
int
|
||||
fseek(FILE *stream, long offset, int whence);
|
||||
|
||||
int
|
||||
fseeko(FILE *stream, off_t offset, int whence);
|
||||
|
||||
/* Current stream position, -1 with errno set on error. */
|
||||
long
|
||||
ftell(FILE *stream);
|
||||
|
||||
__attribute__((pure)) off_t
|
||||
ftello(FILE *stream);
|
||||
|
||||
/* Rewind to the start and clear feof/ferror (equivalent to
|
||||
* fseeko(stream, 0, SEEK_SET) + clearerr). */
|
||||
void
|
||||
rewind(FILE *stream);
|
||||
|
||||
/* Get/set the opaque position via fpos_t. */
|
||||
int
|
||||
fgetpos(FILE *restrict stream, fpos_t *restrict pos);
|
||||
|
||||
int
|
||||
fsetpos(FILE *stream, const fpos_t *pos);
|
||||
|
||||
/* End-of-file and error indicators. */
|
||||
__attribute__((pure)) int
|
||||
feof(FILE *stream);
|
||||
|
||||
__attribute__((pure)) int
|
||||
ferror(FILE *stream);
|
||||
|
||||
void
|
||||
clearerr(FILE *stream);
|
||||
|
||||
/*
|
||||
* Remove the file at path (a directory is removed like rmdir). Returns 0,
|
||||
* or -1 with errno set.
|
||||
*/
|
||||
int
|
||||
remove(const char *path);
|
||||
|
||||
/* Rename oldpath to newpath. Returns 0, or -1 with errno set. */
|
||||
int
|
||||
rename(const char *oldpath, const char *newpath);
|
||||
|
||||
/*
|
||||
* Create an anonymous temporary file ("w+b"): the file is created in /tmp
|
||||
* and unlinked immediately, so it disappears on close. Returns the stream,
|
||||
* or NULL with errno set.
|
||||
*/
|
||||
FILE *
|
||||
tmpfile(void);
|
||||
|
||||
/* The descriptor underlying the stream. */
|
||||
__attribute__((pure)) int
|
||||
fileno(FILE *stream);
|
||||
|
||||
/* getc/putc/getchar/putchar as macros over fgetc/fputc (see above). */
|
||||
#define getc(stream) fgetc(stream)
|
||||
#define putc(c, stream) fputc((c), (stream))
|
||||
#define getchar() fgetc(stdin)
|
||||
#define putchar(c) fputc((c), stdout)
|
||||
|
||||
#if VLIBC_LEVEL_GE(2)
|
||||
|
||||
/*
|
||||
* Generate a name for a temporary file ("/tmp/vlibcXXXXXX" form; the file
|
||||
* is NOT created). With s == NULL a static buffer is used. Not thread-safe,
|
||||
* obsolescent.
|
||||
*/
|
||||
char *
|
||||
tmpnam(char *s);
|
||||
|
||||
/* Controlling terminal path: copies "/dev/tty" into s (or a static
|
||||
* buffer when s == NULL) and returns it. */
|
||||
char *
|
||||
ctermid(char *s);
|
||||
|
||||
/* BSD: like setvbuf with _IOFBF/_IONBF and the given size. */
|
||||
void
|
||||
setbuffer(FILE *stream, char *buf, size_t size);
|
||||
|
||||
/* BSD: select line buffering (setvbuf with _IOLBF and NULL buffer). */
|
||||
void
|
||||
setlinebuf(FILE *stream);
|
||||
|
||||
/* glibc LFS name alias: identical to fopen on LP64. */
|
||||
FILE *
|
||||
fopen64(const char *restrict path, const char *restrict mode);
|
||||
|
||||
#endif /* VLIBC_LEVEL_GE(2) */
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
|
||||
#endif /* VLIBC_STDIO_H */
|
||||
Reference in New Issue
Block a user