<stdio.h>

_IOFBF · _IOLBF · _IONBF · BUFSIZ · EOF · FILE · FILENAME_MAX · FOPEN_MAX · L_tmpnam · NULL · SEEK_CUR · SEEK_END · SEEK_SET · TMP_MAX

clearerr · fclose · feof · ferror · fflush · fgetc · fgetpos · fgets · fopen · fpos_t · fprintf · fputc · fputs · fread · freopen · fscanf · fseek · fsetpos · ftell · fwrite · getc · getchar · gets · perror · printf · putc · putchar · puts · remove · rename · rewind · scanf · setbuf · setvbuf · size_t · snprintf · sprintf · sscanf · stderr · stdin · stdout · tmpfile · tmpnam · ungetc · vfprintf · vfscanf · vprintf · vscanf · vsnprintf · vsprintf · vsscanf

Include the standard header <stdio.h> so that you can perform input and output operations on streams and files.

    /* MACROS */
#define _IOFBF <integer constant expression>
#define _IOLBF <integer constant expression>
#define _IONBF <integer constant expression>
#define BUFSIZ <integer constant expression >= 256>
#define EOF <integer constant expression < 0>
#define FILENAME_MAX <integer constant expression > 0>
#define FOPEN_MAX <integer constant expression >= 8>
#define L_tmpnam <integer constant expression > 0>
#define NULL <either 0, 0L, or (void *)0> [0 in C++]
#define SEEK_CUR <integer constant expression>
#define SEEK_END <integer constant expression>
#define SEEK_SET <integer constant expression>
#define TMP_MAX <integer constant expression >= 25>

#define stderr <pointer to FILE rvalue>
#define stdin <pointer to FILE rvalue>
#define stdout <pointer to FILE rvalue>

    /* TYPES */
typedef o-type FILE;
typedef o-type fpos_t;
typedef ui-type size_t;

    /* FUNCTIONS */
void clearerr(FILE *stream);
int fclose(FILE *stream);
int feof(FILE *stream);
int ferror(FILE *stream);
int fflush(FILE *stream);
FILE *fopen(const char *restrict filename, const char *restrict mode);
FILE *freopen(const char *restrict filename, const char *restrict mode,
    FILE *stream);
int remove(const char *filename);
int rename(const char *old, const char *new);
void rewind(FILE *stream);
void setbuf(FILE *restrict stream, char *restrict buf);
int setvbuf(FILE *restrict stream, char *restrict buf, int mode,
    size_t size);
FILE *tmpfile(void)
char *tmpnam(char *s);

int fseek(FILE *stream, long offset, int mode);
int fsetpos(FILE *stream, const fpos_t *pos);
int fgetpos(FILE *restrict stream, fpos_t *restrict pos);
long ftell(FILE *stream);

int fgetc(FILE *stream);
char *fgets(char *restrict s, int n, FILE *restrict stream);
size_t fread(void *restrict ptr,
    size_t size, size_t nelem, FILE *restrict stream);
int getc(FILE *stream);
int getchar(void);
char *gets(char *s);
int ungetc(int c, FILE *stream);

int fputc(int c, FILE *stream);
int fputs(const char *restrict s, FILE *restrict stream);
size_t fwrite(const void *restrict ptr,
    size_t size, size_t nelem, FILE *restrict stream);
void perror(const char *s);
int putc(int c, FILE *stream);
int putchar(int c);
int puts(const char *s);

int fscanf(FILE *restrict stream, const char *restrict format, ...);
int scanf(const char *restrict format, ...);
int sscanf(const char *restrict s, const char *restrict format, ...);
int vfscanf(FILE *restrict stream, const char *restrict format,
    va_list ap); [added with C99]
int vscanf(const char *restrict format,
    va_list ap); [added with C99]
int vsscanf(const char *restrict s, const char *restrict format,
    va_list ap); [added with C99]

int fprintf(FILE *restrict stream, const char *restrict format, ...);
int printf(const char *restrict format, ...);
int snprintf(char *restrict s, size_t n,
    const char *restrict format, ...); [added with C99]
int sprintf(char *restrict s, const char *restrict format, ...);
int vfprintf(FILE *restrict stream, const char *restrict format,
    va_list ap);
int vprintf(const char *restrict format,
    va_list ap);
int vsnprintf(char *restrict s, size_t n, const char *restrict format,
    va_list ap); [added with C99]
int vsprintf(char *restrict s, const char *restrict format,
    va_list ap);

BUFSIZ

#define BUFSIZ <integer constant expression >= 256>

The macro yields the size of the stream buffer used by setbuf.

clearerr

void clearerr(FILE *stream);

The function clears the end-of-file and error indicators for the stream stream.

EOF

#define EOF <integer constant expression < 0>

The macro yields the return value used to signal the end of a stream or to report an error condition.

fclose

int fclose(FILE *stream);

The function closes the file associated with the stream stream. It returns zero if successful; otherwise, it returns EOF. fclose writes any buffered output to the file, deallocates the stream buffer if it was automatically allocated, and removes the association between the stream and the file. Do not use the value of stream in subsequent expressions.

feof

int feof(FILE *stream);

The function returns a nonzero value if the end-of-file indicator is set for the stream stream.

ferror

int ferror(FILE *stream);

The function returns a nonzero value if the error indicator is set for the stream stream.

fflush

int fflush(FILE *stream);

The function writes any buffered output to the file associated with the stream stream and returns zero if successful; otherwise, it returns EOF. If stream is a null pointer, fflush writes any buffered output to all files opened for output.

fgetc

int fgetc(FILE *stream);

The function reads the next character c (if present) from the input stream stream, advances the file-position indicator (if defined), and returns (int)(unsigned char)c. If the function sets either the end-of-file indicator or the error indicator, it returns EOF.

fgetpos

int fgetpos(FILE *restrict stream, fpos_t *restrict pos);

The function stores the file-position indicator for the stream stream in *pos and returns zero if successful; otherwise, the function stores a positive value in errno and returns a nonzero value.

fgets

char *fgets(char *restrict s, int n, FILE *restrict stream);

The function reads characters from the input stream stream and stores them in successive elements of the array beginning at s and continuing until it stores n-1 characters, stores an NL character, or sets the end-of-file or error indicators. If fgets stores any characters, it concludes by storing a null character in the next element of the array. It returns s if it stores any characters and it has not set the error indicator for the stream; otherwise, it returns a null pointer. If it sets the error indicator, the array contents are indeterminate.

FILE

typedef o-type FILE;

The type is an object type o-type that stores all control information for a stream. The functions fopen and freopen allocate all FILE objects used by the read and write functions.

FILENAME_MAX

#define FILENAME_MAX <integer constant expression > 0>

The macro yields the maximum size array of characters that you must provide to hold a filename.

fopen

FILE *fopen(const char *restrict filename, const char *restrict mode);

The function opens the file with the filename filename, associates it with a stream, and returns a pointer to the object controlling the stream. If the open fails, it returns a null pointer. The initial characters of mode determine how the program manipulates the stream and whether it interprets the stream as text or binary. The initial characters must be one of the following sequences:

• "r" -- to open an existing text file for reading
• "w" -- to create a text file or to open and truncate an existing text file, for writing
• "a" -- to create a text file or to open an existing text file, for writing. The file-position indicator is positioned at the end of the file before each write
• "rb" -- to open an existing binary file for reading
• "wb" -- to create a binary file or to open and truncate an existing binary file, for writing
• "ab" -- to create a binary file or to open an existing binary file, for writing. The file-position indicator is positioned at the end of the file (possibly after arbitrary null byte padding) before each write
• "r+" -- to open an existing text file for reading and writing
• "w+" -- to create a text file or to open and truncate an existing text file, for reading and writing
• "a+" -- to create a text file or to open an existing text file, for reading and writing. The file-position indicator is positioned at the end of the file before each write
• "r+b" or "rb+" -- to open an existing binary file for reading and writing
• "w+b" or "wb+" -- to create a binary file or to open and truncate an existing binary file, for reading and writing
• "a+b" or "ab+" -- to create a binary file or to open an existing binary file, for reading and writing. The file-position indicator is positioned at the end of the file (possibly after arbitrary null byte padding) before each write

If you open a file for both reading and writing, the target environment can open a binary file instead of a text file. If the file is not interactive, the stream is fully buffered.

FOPEN_MAX

#define FOPEN_MAX <integer constant expression >= 8>

The macro yields the maximum number of files that the target environment permits to be simultaneously open (including stderr, stdin, and stdout).

fpos_t

typedef o-type fpos_t;

The type is an object type o-type of an object that you declare to hold the value of a file-position indicator stored by fsetpos and accessed by fgetpos.

fprintf

int fprintf(FILE *restrict stream, const char *restrict format, ...);

The function generates formatted text, under the control of the format format and any additional arguments, and writes each generated character to the stream stream. It returns the number of characters generated, or it returns a negative value if the function sets the error indicator for the stream.

fputc

int fputc(int c, FILE *stream);

The function writes the character (unsigned char)c to the output stream stream, advances the file-position indicator (if defined), and returns (int)(unsigned char)c. If the function sets the error indicator for the stream, it returns EOF.

fputs

int fputs(const char *restrict s, FILE *restrict stream);

The function accesses characters from the C string s and writes them to the output stream stream. The function does not write the terminating null character. It returns a nonnegative value if it has not set the error indicator; otherwise, it returns EOF.

fread

size_t fread(void *restrict ptr,
    size_t size, size_t nelem, FILE *restrict stream);

The function reads characters from the input stream stream and stores them in successive elements of the array whose first element has the address (char *)ptr until the function stores size*nelem characters or sets the end-of-file or error indicator. It returns n/size, where n is the number of characters it read. If n is not a multiple of size, the value stored in the last element is indeterminate. If the function sets the error indicator, the file-position indicator is indeterminate.

freopen

FILE *freopen(const char *restrict filename, const char *restrict mode,
    FILE *stream);

The function closes the file associated with the stream stream (as if by calling fclose); then it opens the file with the filename filename and associates the file with the stream stream (as if by calling fopen(filename, mode)). It returns stream if the open is successful; otherwise, it returns a null pointer.

fscanf

int fscanf(FILE *restrict stream, const char *restrict format, ...);

The function scans formatted text, under the control of the format format and any additional arguments. It obtains each scanned character from the stream stream. It returns the number of input items matched and assigned, or it returns EOF if the function does not store values before it sets the end-of-file or error indicator for the stream.

fseek

int fseek(FILE *stream, long offset, int mode);

The function sets the file-position indicator for the stream stream (as specified by offset and mode), clears the end-of-file indicator for the stream, and returns zero if successful.

For a binary stream, offset is a signed offset in bytes:

• If mode has the value SEEK_SET, fseek adds offset to the file-position indicator for the beginning of the file.
• If mode has the value SEEK_CUR, fseek adds offset to the current file-position indicator.
• If mode has the value SEEK_END, fseek adds offset to the file-position indicator for the end of the file (possibly after arbitrary null character padding).

fseek sets the file-position indicator to the result of this addition.

For a text stream:

• If mode has the value SEEK_SET, fseek sets the file-position indicator to the value encoded in offset, which is either a value returned by an earlier successful call to ftell or zero to indicate the beginning of the file.
• If mode has the value SEEK_CUR and offset is zero, fseek leaves the file-position indicator at its current value.
• If mode has the value SEEK_END and offset is zero, fseek sets the file-position indicator to indicate the end of the file.

The function defines no other combination of argument values.

fsetpos

int fsetpos(FILE *stream, const fpos_t *pos);

The function sets the file-position indicator for the stream stream to the value stored in *pos, clears the end-of-file indicator for the stream, and returns zero if successful. Otherwise, the function stores a positive value in errno and returns a nonzero value.

ftell

long ftell(FILE *stream);

The function returns an encoded form of the file-position indicator for the stream stream or stores a positive value in errno and returns the value -1. For a binary file, a successful return value gives the number of bytes from the beginning of the file. For a text file, target environments can vary on the representation and range of encoded file-position indicator values.

fwrite

size_t fwrite(const void *restrict ptr,
    size_t size, size_t nelem, FILE *stream);

The function writes characters to the output stream stream, accessing values from successive elements of the array whose first element has the address (char *)ptr until the function writes size*nelem characters or sets the error indicator. It returns n/size, where n is the number of characters it wrote. If the function sets the error indicator, the file-position indicator is indeterminate.

getc

int getc(FILE *stream);

The function has the same effect as fgetc(stream) except that a macro version of getc can evaluate stream more than once.

getchar

int getchar(void);

The function has the same effect as fgetc(stdin), reading a character from the stream stdin

gets

char *gets(char *s);

The function reads characters from the stream stdin and stores them in successive elements of the array whose first element has the address s until the function reads an NL character (which is not stored) or sets the end-of-file or error indicator. If gets reads any characters, it concludes by storing a null character in the next element of the array. It returns s if it reads any characters and has not set the error indicator for the stream; otherwise, it returns a null pointer. If it sets the error indicator, the array contents are indeterminate. The number of characters that gets reads and stores cannot be limited. Use fgets instead.

_IOFBF

#define _IOFBF <integer constant expression>

The macro yields the value of the mode argument to setvbuf to indicate full buffering. (Flush the stream buffer only when it fills.)

_IOLBF

#define _IOLBF <integer constant expression>

The macro yields the value of the mode argument to setvbuf to indicate line buffering. (Flush the stream buffer at the end of a text line.)

_IONBF

#define _IONBF <integer constant expression>

The macro yields the value of the mode argument to setvbuf to indicate no buffering. (Flush the stream buffer at the end of each write operation.)

L_tmpnam

#define L_tmpnam <integer constant expression > 0>

The macro yields the number of characters that the target environment requires for representing temporary filenames created by tmpnam.

NULL

#define NULL <either 0, 0L, or (void *)0> [0 in C++]

The macro yields a null pointer constant that is usable as an address constant expression.

perror

void perror(const char *s);

The function writes a line of text to the stream stderr. If s is not a null pointer, the function first writes the C string s (as if by calling fputs(s, stderr)), followed by a colon (:) and a space. It then writes the same message C string that is returned by strerror(errno), converting the value stored in errno, followed by an NL.

printf

int printf(const char *restrict format, ...);

The function generates formatted text, under the control of the format format and any additional arguments, and writes each generated character to the stream stdout. It returns the number of characters generated, or it returns a negative value if the function sets the error indicator for the stream.

putc

int putc(int c, FILE *stream);

The function has the same effect as fputc(c, stream) except that a macro version of putc can evaluate stream more than once.

putchar

int putchar(int c);

The function has the same effect as fputc(c, stdout), writing a character to the stream stdout.

puts

int puts(const char *s);

The function accesses characters from the C string s and writes them to the stream stdout. The function writes an NL character to the stream in place of the terminating null character. It returns a nonnegative value if it has not set the error indicator; otherwise, it returns EOF.

remove

int remove(const char *filename);

The function removes the file with the filename filename and returns zero if successful. If the file is open when you remove it, the result is implementation defined. After you remove it, you cannot open it as an existing file.

rename

int rename(const char *old, const char *new);

The function renames the file with the filename old to have the filename new and returns zero if successful. If a file with the filename new already exists, the result is implementation defined. After you rename it, you cannot open the file with the filename old.

rewind

void rewind(FILE *stream);

The function calls fseek(stream, 0L, SEEK_SET) and then clears the error indicator for the stream stream.

scanf

int scanf(const char *restrict format, ...);

The function scans formatted text, under the control of the format format and any additional arguments. It obtains each scanned character from the stream stdin. It returns the number of input items matched and assigned, or it returns EOF if the function does not store values before it sets the end-of-file or error indicators for the stream.

SEEK_CUR

#define SEEK_CUR <integer constant expression>

The macro yields the value of the mode argument to fseek to indicate seeking relative to the current file-position indicator.

SEEK_END

#define SEEK_END <integer constant expression>

The macro yields the value of the mode argument to fseek to indicate seeking relative to the end of the file.

SEEK_SET

#define SEEK_SET <integer constant expression>

The macro yields the value of the mode argument to fseek to indicate seeking relative to the beginning of the file.

setbuf

void setbuf(FILE *restrict stream, char *restrict buf);

If buf is not a null pointer, the function calls setvbuf(stream, buf, __IOFBF, BUFSIZ), specifying full buffering with _IOFBF and a buffer size of BUFSIZ characters. Otherwise, the function calls setvbuf(stream, 0, _IONBF, BUFSIZ), specifying no buffering with _IONBF.

setvbuf

int setvbuf(FILE *restrict stream, char *restrict buf, int mode,
    size_t size);

The function sets the buffering mode for the stream stream according to buf, mode, and size. It returns zero if successful. If buf is not a null pointer, then buf is the address of the first element of an array of char of size size that can be used as the stream buffer. Otherwise, setvbuf can allocate a stream buffer that is freed when the file is closed. For mode you must supply one of the following values:

• _IOFBF -- to indicate full buffering
• _IOLBF -- to indicate line buffering
• _IONBF -- to indicate no buffering

You must call setvbuf after you call fopen to associate a file with that stream and before you call a library function that performs any other operation on the stream.

size_t

typedef ui-type size_t;

The type is the unsigned integer type ui-type of an object that you declare to store the result of the sizeof operator.

snprintf

int snprintf(char *restrict s, size_t n,
    const char *restrict format, ...); [added with C99]

The function generates formatted text, under the control of the format format and any additional arguments, and stores each generated character in successive locations of the array object whose first element has the address s. If n is zero, it stores no characters. Otherwise, the function stores up to n - 1 characters and concludes by storing a null character in the next location of the array. It returns the number of characters generated -- not including the null character.

sprintf

int sprintf(char *restrict s, const char *restrict format, ...);

The function generates formatted text, under the control of the format format and any additional arguments, and stores each generated character in successive locations of the array object whose first element has the address s. The function concludes by storing a null character in the next location of the array. It returns the number of characters generated -- not including the null character.

sscanf

int sscanf(const char *restrict s, const char *restrict format, ...);

The function scans formatted text, under the control of the format format and any additional arguments. It accesses each scanned character from successive locations of the array object whose first element has the address s. It returns the number of items matched and assigned, or it returns EOF if the function does not store values before it accesses a null character from the array.

stderr

#define stderr <pointer to FILE rvalue>

The macro yields a pointer to the object that controls the standard error output stream.

stdin

#define stdin <pointer to FILE rvalue>

The macro yields a pointer to the object that controls the standard input stream.

stdout

#define stdout <pointer to FILE rvalue>

The macro yields a pointer to the object that controls the standard output stream.

tmpfile

FILE *tmpfile(void)

The function creates a temporary binary file with the filename temp-name and then has the same effect as calling fopen(temp-name, "wb+"). The file temp-name is removed when the program closes it, either by calling fclose explicitly or at normal program termination. The filename temp-name does not conflict with any filenames that you create. If the open is successful, the function returns a pointer to the object controlling the stream; otherwise, it returns a null pointer.

TMP_MAX

#define TMP_MAX <integer constant expression >= 25>

The macro yields the minimum number of distinct filenames created by the function tmpnam.

tmpnam

char *tmpnam(char *s);

The function creates a unique filename temp-name and returns a pointer to the filename. If s is not a null pointer, then s must be the address of the first element of an array at least of size L_tmpnam. The function stores temp-name in the array and returns s. Otherwise, if s is a null pointer, the function stores temp-name in a static-duration array and returns the address of its first element. Subsequent calls to tmpnam can alter the values stored in this array.

The function returns unique filenames for each of the first TMP_MAX times it is called, after which its behavior is implementation defined. The filename temp-name does not conflict with any filenames that you create.

ungetc

int ungetc(int c, FILE *stream);

If c is not equal to EOF, the function stores (unsigned char)c in the object whose address is stream and clears the end-of-file indicator. If c equals EOF or the store cannot occur, the function returns EOF; otherwise, it returns (unsigned char)c. A subsequent library function call that reads a character from the stream stream obtains this stored value, which is then forgotten.

Thus, you can effectively push back a character to a stream after reading a character. (You need not push back the same character that you read.) An implementation can let you push back additional characters before you read the first one. You read the characters in reverse order of pushing them back to the stream. You cannot portably:

• push back more than one character
• push back a character if the file-position indicator is at the beginning of the file
• Call ftell for a text file that has a character currently pushed back

A call to the functions fseek, fsetpos, or rewind for the stream causes the stream to forget any pushed-back characters. For a binary stream, the file-position indicator is decremented for each character that is pushed back.

vfprintf

int vfprintf(FILE *restrict stream, const char *restrict format,
     va_list ap);

The function generates formatted text, under the control of the format format and any additional arguments, and writes each generated character to the stream stream. It returns the number of characters generated, or it returns a negative value if the function sets the error indicator for the stream.

The function accesses additional arguments by using the context information designated by ap. The program must execute the macro va_start before it calls the function, and then execute the macro va_end after the function returns.

vfscanf

int vfscanf(FILE *restrict stream, const char *restrict format,
    va_list ap); [added with C99]

The function scans formatted text, under the control of the format format and any additional arguments. It obtains each scanned character from the stream stream. It returns the number of input items matched and assigned, or it returns EOF if the function does not store values before it sets the end-of-file or error indicator for the stream.

The function accesses additional arguments by using the context information designated by ap. The program must execute the macro va_start before it calls the function, and then execute the macro va_end after the function returns.

vprintf

int vprintf(const char *restrict format,
    va_list ap);

The function generates formatted text, under the control of the format format and any additional arguments, and writes each generated character to the stream stdout. It returns the number of characters generated, or a negative value if the function sets the error indicator for the stream.

The function accesses additional arguments by using the context information designated by ap. The program must execute the macro va_start before it calls the function, and then execute the macro va_end after the function returns.

vscanf

int vscanf(const char *restrict format,
    va_list ap); [added with C99]

The function scans formatted text, under the control of the format format and any additional arguments. It obtains each scanned character from the stream stdin. It returns the number of input items matched and assigned, or it returns EOF if the function does not store values before it sets the end-of-file or error indicators for the stream.

The function accesses additional arguments by using the context information designated by ap. The program must execute the macro va_start before it calls the function, and then execute the macro va_end after the function returns.

vsnprintf

int vsnprintf(char *restrict s, size_t n, const char *restrict format,
    va_list ap); [added with C99]

The function generates formatted text, under the control of the format format and any additional arguments, and stores each generated character in successive locations of the array object whose first element has the address s. If n is zero, it stores no characters. Otherwise, the function stores up to n - 1 characters and concludes by storing a null character in the next location of the array. It returns the number of characters generated -- not including the null character.

The function accesses additional arguments by using the context information designated by ap. The program must execute the macro va_start before it calls the function, and then execute the macro va_end after the function returns.

vsprintf

int vsprintf(char *restrict s, const char *restrict format,
    va_list ap);

The function generates formatted text, under the control of the format format and any additional arguments, and stores each generated character in successive locations of the array object whose first element has the address s. The function concludes by storing a null character in the next location of the array. It returns the number of characters generated -- not including the null character.

The function accesses additional arguments by using the context information designated by ap. The program must execute the macro va_start before it calls the function, and then execute the macro va_end after the function returns.

vsscanf

int vsscanf(const char *restrict s, const char *restrict format,
    va_list ap); [added with C99]

The function scans formatted text, under the control of the format format and any additional arguments. It accesses each scanned character from successive locations of the array object whose first element has the address s. It returns the number of items matched and assigned, or it returns EOF if the function does not store values before it accesses a null character from the array.

The function accesses additional arguments by using the context information designated by ap. The program must execute the macro va_start before it calls the function, and then execute the macro va_end after the function returns.

See also the Table of Contents and the Index.

Copyright © 1992-2006 by P.J. Plauger and Jim Brodie. All rights reserved.