File System Component  Version 6.6
MDK-Professional Middleware for Devices with Flash File System
 All Data Structures Files Functions Variables Enumerations Enumerator Macros Groups Pages
Standard I/O Routines

Standard I/O Routines perform input and output operations on files. More...

Functions

int fclose (FILE *stream)
 Close file stream.
 
int fflush (FILE *stream)
 Flush file stream.
 
FILE * fopen (const char *filename, const char *mode)
 Open file stream.
 
FILE * freopen (const char *filename, const char *mode, FILE *stream)
 Reopen file stream.
 
void setbuf (FILE *stream, char *buf)
 Buffer stream.
 
int setvbuf (FILE *stream, char *buf, int mode, size_t size)
 Buffer stream.
 
int fprintf (FILE *stream, const char *format,...)
 Write formatted string to file stream.
 
int fscanf (FILE *stream, const char *format,...)
 Read formatted string from file stream.
 
int vfscanf (FILE *stream, const char *format, va_list arg)
 
int vfprintf (FILE *stream, const char *format, va_list arg)
 
int fgetc (FILE *stream)
 Read character from file stream.
 
char * fgets (char *s, int n, FILE *stream)
 Read string from file stream.
 
int fputc (int c, FILE *stream)
 Write character to file stream.
 
int fputs (const char *s, FILE *stream)
 Write string to file stream.
 
int getc (FILE *stream)
 Read character from file stream (unsafe).
 
int putc (int c, FILE *stream)
 Write character to file stream (unsafe).
 
int ungetc (int c, FILE *stream)
 Stores a character into an input file stream.
 
size_t fread (void *ptr, size_t size, size_t nmemb, FILE *stream))
 Read number of bytes from file stream.
 
size_t fwrite (const void *ptr, size_t size, size_t nmemb, FILE *stream))
 Write number of bytes to file stream.
 
int fgetpos (FILE *stream, fpos_t *pos)
 Store current value of file position indicator.
 
int fseek (FILE *stream, long int offset, int whence)
 Move file stream's in-file pointer to new location.
 
int fsetpos (FILE *stream, const fpos_t *pos)
 Set file position indicator.
 
long int ftell (FILE *stream)
 Get current location of stream's in-file pointer.
 
void rewind (FILE *stream)
 Move file stream's in-file pointer to beginning of file.
 
void clearerr (FILE *stream)
 Clear end-of-file and error indicators.
 
int feof (FILE *stream)
 Report whether end of stream has been reached.
 
int ferror (FILE *stream)
 Report whether there is an error in file stream.
 

Description

Input and Output operations are performed in C using the Standard Input and Output Library (stdio.h). This library uses streams to operate with physical devices such as keyboards, printers, terminals or with any other type of files supported by the system. Streams are used to interact with all these devices in the same way. All streams share similar properties, regardless of the physical media they are associated with.

In the stdio library, all streams are defined as pointers to FILE objects, being used as a parameter in the operations involving the stream.

Three standard streams are available: stdin, stdout and stderr. They are automatically being created and opened for all programs using the stdio library.

Function Documentation

void clearerr ( FILE *  stream)
Parameters
streamFile pointer specifying the data stream.
Returns
no value.

The function clearerr clears the end-of-file and error indicators for the stream pointed to by stream.

These indicators are cleared when the file is opened or by an explicit call to the clearerr, rewind, fseek, or fsetpos function.

Code Example

#include <stdio.h> /* Standard I/O .h-file */
#include "rl_fs.h" /* FileSystem definitions */
void main (void)
{
FILE * stream;
stream = fopen("file.txt","r");
if (stream==NULL) perror ("Can't open file");
else {
fputc ('x',stream);
if (ferror (stream)) {
printf ("Error: Cannot write to file.txt\n");
clearerr (stream);
}
fgetc (stream);
if (!ferror (stream))
printf ("No errors reading file.txt\n");
fclose (stream);
}
return 0;
}
int fclose ( FILE *  stream)
Parameters
streamFile pointer specifying the data stream.
Returns
status information:
  • 0 if the stream was successfully closed.
  • nonzero if errors were detected or if stream was already closed.

The function fclose causes the stream to be flushed and the associated file to be closed. Any unwritten buffered data for the stream are delivered to the host environment to be written to the file; any unread buffered data are discarded. The stream is disassociated from the file. If the associated buffer was automatically allocated, it is deallocated.

The argument stream is a file pointer specifying the data stream.

Code Example

#include <stdio.h> /* Standard I/O .h-file */
#include "rl_fs.h" /* FileSystem definitions */
void tst_fclose (void) {
FILE *fin;
fin = fopen ("Test.txt","r");
if (fin == NULL) {
printf ("File not found!\n");
}
else {
// process file content
if (fclose (fin)) {
printf ("File closed!\n");
}
else {
printf ("File could not be closed!\n");
}
}
}
int feof ( FILE *  stream)
Parameters
streamFile pointer specifying the data stream.
Returns
status information:
  • 0 if data stream can be read.
  • non-zero value if end-of-file condition occurred.

The function feof determines whether an end-of-file condition has occurred.

The argument stream is a file pointer specifying a data stream.

Code Example

#include <stdio.h> /* Standard I/O .h-file */
#include "rl_fs.h" /* FileSystem definitions */
void tst_feof (void) {
FILE *fin;
char ch;
if (fin = fopen ("Test_feof") != NULL) {
// Read all characters from the file
while (!feof (fin)) {
ch = fgetc (fin);
}
fclose (fin);
}
}
int ferror ( FILE *  stream)
Parameters
streamFile pointer specifying the data stream.
Returns
status information:
  • 0 if there are no errors.
  • non-zero value if errors occurred.

The function ferror tests a data stream for read or write errors.

The argument stream is a pointer defining the data stream. If an error has occurred, the error indicator remains set until the file is closed or rewound.

Code Example

#include <stdio.h> /* Standard I/O .h-file */
#include "rl_fs.h" /* FileSystem definitions */
void tst_ferror (void) {
FILE *fin;
if (fin = fopen ("Test_ferror") != NULL) {
// Read all characters from the file
while (!feof (fin)) {
printf ("%s\n", fgetc (fin));
}
if (ferror (fin)) {
printf ("Errors occurred while reading the file!\n");
}
fclose (fin);
}
}
int fflush ( FILE *  stream)
Parameters
streamFile pointer specifying the data stream.
Returns
status information:
  • nonzero if write error has occurred.

The function fflush enforces a write operation to a data stream. Associated buffers are emptied and the content is written to the file. The function writes the File Allocation Record to the File System along with the file data. fflush leaves the file open.

The argument stream is a pointer defining the data stream.

Note
On FAT drives, fflush will only flush buffer in the File System Component and flushed content will remain in the File System cache buffers. To write entire file content on FAT drive and create a consistent file with proper size, you must close the file using the fclose library function.

Code Example

#include <stdio.h> /* Standard I/O .h-file */
#include "rl_fs.h" /* FileSystem definitions */
void main (void) {
FILE *fout;
int i;
fout = fopen ("Flush.test", "w");
if (fout != NULL) {
for (i = 'A'; i < 'Z'; i++) {
fputc (i, fout);
}
// Now flush the file buffers
if (fflush (fout)) {
printf ("An error occurred while flushing the buffer.\n");
}
else {
printf ("Writing to the file went OK.\n");
}
fclose (fout);
}
}
int fgetc ( FILE *  stream)
Parameters
streamFile pointer specifying the data stream.
Returns
status information:
  • Integer: representing the character.
  • EOF: on error or end-of-file condition.

The function fgetc reads a single character from a data steam and moves the pointer to the next character.

The argument stream is a pointer defining the data steam.

Code Example

#include <stdio.h> /* Standard I/O .h-file */
#include "rl_fs.h" /* FileSystem definitions */
void tst_fgetc (void) {
FILE *fin;
int ch;
fin = fopen ("Test.txt","r");
if (fin != NULL) {
// dump the character to a screen
while ((ch = fgetc (fin)) != EOF) {
putchar (ch);
}
fclose (fin);
}
}
int fgetpos ( FILE *  stream,
fpos_t *  pos 
)
Parameters
streamFile pointer specifying the data stream.
posPointer specifying the current value of the file position indicator.
Returns
status information:
  • 0 if successful.
  • Otherwise nonzero is returned and the integer expression errno is set to an implementation-defined nonzero value.

The function stores the current value of the file position indicator for the stream pointed to by stream in the object pointed to by pos. The value stored contains unspecified information usable by the fsetpos function for repositioning the stream to its position at the time of the call to the fgetpos function.

Code Example

#include <stdio.h> /* Standard I/O .h-file */
#include "rl_fs.h" /* FileSystem definitions */
int main (void)
{
FILE * stream;
int c;
fpos_t pos;
stream = fopen ("file.txt","r");
if (stream==NULL) {
perror ("Error: Cannot open file");
}
else {
c = fgetc (stream);
printf ("1st character is %c\n",c);
fgetpos (stream,&pos);
fsetpos (stream,&pos);
c = fgetc (stream);
printf ("2nd character is %c\n",c);
fclose (stream);
}
return 0;
}
char * fgets ( char *  s,
int  n,
FILE *  stream 
)
Parameters
sPointer specifying the storage buffer.
nSpecifies the number of characters to read.
streamFile pointer specifying the data stream.
Returns
status information:
  • s if successful.
  • NULL: If end-of-file is encountered or a read error occurs and no characters.

The function fgets reads a string from a data steam.

The argument s is a pointer defining the buffer to store the string.

The function reads at most one less than the number of characters specified by the argument n.

The argument stream is a pointer defining the data stream to read from.

Characters are read from the current cursor position:

  • until length characters have been read.
  • up to and including the first new-line ('
    ').
  • up to the end of the stream.

A null character ('\0') is appended to s.

Code Example

#include <stdio.h> /* Standard I/O .h-file */
#include "rl_fs.h" /* FileSystem definitions */
void tst_fgets (void) {
FILE *fin;
char line[80];
fin = fopen ("Test.txt","r");
if (fin != NULL) {
while (fgets (line, sizeof (line), fin) != NULL) {
puts (line);
}
fclose (fin);
}
}
FILE * fopen ( const char *  filename,
const char *  mode 
)
Parameters
filenameFile pointer specifying the file to open.
modePointer defining the access type.
Returns
a pointer to object controlling stream. If the open operation fails, fopen returns a null pointer.

The function fopen opens a file for reading or writing.

The argument filename is a pointer defining the file to open. It can contain a path. If the path does not exist, all subfolders are created. The path may contain drive prefixes. If the drive prefix is omitted, the Current Drive is used.

The argument mode is a pointer defining the access type and can have the following values:

ModeDescription
"r" Read mode. Opens a file for reading.
"w" Write mode. Opens an empty file for writing. If the file exists, the content is destroyed. If the file does not exist, an empty file is opened for writing.
"a" Append mode. Opens a file for appending text. If the file already exists, data is appended. If the file does not exist, an empty file is opened for writing. Opening a file with append mode causes all subsequent writes to be placed at the then current end-of-file, regardless of interfering calls to fseek.
"b" Binary mode. Can be appended to any character above, but has no effect. The character is allowed for ISO C standard conformance.
"+" Update mode. Can be used with any character above as a second or third character. When a file is opened with update mode, both reading and writing can be performed. Programmers must ensure that reading is not directly followed by writing without an interfering call to fflush or to a file positioning function (fseek or rewind). Also, writing should not be followed directly by reading without an interfering call to a file positioning function, unless the writing operation encounters EOF.
Note
File update modes are only supported on FAT file system!

Code Example

#include <stdio.h> /* Standard I/O .h-file */
#include "rl_fs.h" /* FileSystem definitions */
void tst_fopen (void) {
FILE *f;
f = fopen ("Test.txt","r"); /* Open a file from current drive. */
if (f == NULL) {
printf ("File not found!\n");
}
else {
// process file content
fclose (f);
}
f = fopen ("M:\\Temp_Files\\Dump_file.log","w"); /* Create a file in subfolder on SD card.*/
if (f == NULL) {
printf ("Failed to create a file!\n");
}
else {
// write data to file
fclose (f);
}
}
int fprintf ( FILE *  stream,
const char *  format,
  ... 
)
Parameters
streamFile pointer specifying the data stream.
formatPointer specifying the output format.
Returns
status information:
  • Number of characters transmitted.
  • Negative value if an output error occurred.

The function fprintf writes a string to a data stream.

The argument stream is a pointer defining the data stream. The argument format is a pointer defining the format for the output. The rules correspond to the standard printf formatting string. The optional arguments are converted and output according to the corresponding format specifications in format.

Code Example

#include <stdio.h> /* Standard I/O .h-file */
#include "rl_fs.h" /* FileSystem definitions */
void tst_fprintf (void) {
FILE *fout;
int i = 56;
fout = fopen ("Test.txt","w");
if (fout == NULL) {
printf ("File open error!\n");
}
else {
fprintf (fout, "printf test: val = %i fval =%f\n", i, i * 3.45);
fclose (fout);
}
}
int fputc ( int  c,
FILE *  stream 
)
Parameters
cInteger value specifying the character to write.
streamFile pointer specifying the data stream.
Returns
status information:
  • the character written if successful.
  • EOF: on error.

The function fputc writes a character to a data stream.

The argument c is an integer value defining the character to write.

The argument stream is a file pointer defining the data stream.

Code Example

#include <stdio.h> /* Standard I/O .h-file */
#include "rl_fs.h" /* FileSystem definitions */
void tst_fputc (void) {
FILE *fout;
int ch;
fout = fopen ("Test.txt","w");
if (fout != NULL) {
while ((ch = getchar ()) != EOF) {
fputc (ch, fout); /* copy the stdin to a file */
}
fclose (fout);
}
}
int fputs ( const char *  s,
FILE *  stream 
)
Parameters
sConstant character pointer specifying the string to write.
streamFile pointer specifying the data stream.
Returns
status information:
  • non-negative number if successful.
  • EOF: on error.

The function fputs writes a string to a data stream.

The argument s is a constant character pointer defining the string to write.

The argument stream is a file pointer defining the data stream.

Code Example

#include <stdio.h> /* Standard I/O .h-file */
#include "rl_fs.h" /* FileSystem definitions */
void tst_fputs (void) {
FILE *fout;
fout = fopen ("Test.txt","w");
if (fout != NULL) {
fputs("This is an example for fputs.\n", fout);
fclose (fout);
}
}
size_t fread ( void *  ptr,
size_t  size,
size_t  nmemb,
FILE *  stream 
)
Parameters
ptrVoid pointer specifying the storage buffer.
sizeDefines the item size in bytes.
nmembDefines the number of items to read.
streamFile pointer specifying the data stream.
Returns
the number of members successfully read, which may be less than nmemb if a read error or end-of-file is encountered. If size or nmemb is zero, fread returns zero and the contents of the array and the state of the stream remain unchanged.

The function fread reads a number of items with a given size from a data stream to a buffer.

The argument ptr is a void pointer to a buffer to store the items read.

The argument size defines the item size in bytes.

The argument nmemb defines the number of items to read.

The argument stream is a file pointer defining the data stream to read.

Note
The file position indicator is undefined when errors occurred.

Code Example

#include <stdio.h> /* Standard I/O .h-file */
#include "rl_fs.h" /* FileSystem definitions */
void tst_fread (void) {
int count[10];
FILE *fin;
fin = fopen ("Counter.log","r");
if (fin != NULL) {
fread (&count[0], sizeof (int), 10, fin);
fclose (fin);
}
}
FILE * freopen ( const char *  filename,
const char *  mode,
FILE *  stream 
)
Parameters
filenameFile pointer specifying the file to open.
modePointer defining the access type.
streamFile pointer specifying the data stream.
Returns
a pointer to object controlling stream. If the open operation fails, fopen returns a null pointer.

The function freopen first attempts to close any file that is associated with the specified stream. Failure to close the file successfully is ignored. The error and end-of-file indicators for the stream are cleared. freopen opens a file whose name is the string pointed to by filename and associates the stream pointed to by stream with it.

The argument mode is used just as in the fopen function.

Code Example

#include <stdio.h> /* Standard I/O .h-file */
#include "rl_fs.h" /* FileSystem definitions */
void tst_freopen (void) {
FILE *f;
f = freopen ("Test.txt","r"); /* Open a file from current drive. */
// do some file manipulation here
fclose (f);
}
int fscanf ( FILE *  stream,
const char *  format,
  ... 
)
Parameters
streamFile pointer specifying the data stream.
formatPointer specifying the formatting string.
Returns
number of successfully converted input fields.

The function fscanf reads values from a data stream and stores them with the specified format to a variable.

The argument stream is a file pointer defining the data stream to read. The argument format is a character pointer defining the formatting string. The parameters additional arguments store the data according to the format string format. Each argument must be a pointer to a variable corresponding to the type defined in format.

Code Example

#include <stdio.h> /* Standard I/O .h-file */
#include "rl_fs.h" /* FileSystem definitions */
void tst_fread (void) {
int index, count;
FILE *fin;
fin = fopen ("Counter.log","r");
if (fin != NULL) {
fscanf (fin, "%d, %d",&index, &count);
fclose (fin);
}
}
int fseek ( FILE *  stream,
long int  offset,
int  whence 
)
Parameters
streamFile pointer specifying the data stream.
offsetFile Long integer value specifying the number of bytes to move.
whenceInteger defining the cursor location.
Returns
status information:
  • 0 on success.
  • EOF on error.

The function fseek positions the file cursor to a new location.

The argument stream is a file pointer defining the file.

The argument offset is a long value defining the number of bytes to move.

The argument whence is an integer defining the file cursor location.

The argument whence can have one of the following values:

Origin ValueDescription
SEEK_CUR Current position of the file cursor
SEEK_END End of the file
SEEK_SET Beginning of the file

The file cursor can be positioned anywhere within the file or past the end of the file.

Note
  • On a 32-bit system, an object of type long int consists of 32-bits. Seeking capabilities are therefore limited to the area of two gigabytes.
  • When using EFS, fseek works only for files opened in read mode. Seeking within files opened for writing is not supported.

Code Example

#include <stdio.h> /* Standard I/O .h-file */
#include "rl_fs.h" /* FileSystem definitions */
void tst_fseek (void) {
FILE *fin;
char ch;
fin = fopen ("Test.txt","r");
if (fin != NULL) {
fseek (fin, 5L, SEEK_SET); // Read the 5th character from file
ch = fgetc (fin);
fseek (fin, -1L, SEEK_END); // Read the last character from file
ch = fgetc (fin);
fclose (fin);
}
}
int fsetpos ( FILE *  stream,
const fpos_t *  pos 
)
Parameters
streamFile pointer specifying the data stream.
posPointer specifying the value of the file position indicator that is to be set.
Returns
status information:
  • 0 if successful.
  • Otherwise nonzero is returned and the integer expression errno is set to an implementation-defined nonzero value.

The function fsetpos sets the file position indicator for the stream pointed to by stream according to the value of the object pointed to by pos, which shall be a value returned by an earlier call to the fgetpos function on the same stream.

The fsetpos function clears the end-of-file indicator and undoes any effects of the ungetc function on the same stream. After an fsetpos call, the next operation on an update stream may be either input or output.

Code Example

#include <stdio.h> /* Standard I/O .h-file */
#include "rl_fs.h" /* FileSystem definitions */
int main (void)
{
FILE * stream;
int c;
fpos_t pos;
stream = fopen ("file.txt","r");
if (stream==NULL) {
perror ("Error: Cannot open file");
}
else {
c = fgetc (stream);
printf ("1st character is %c\n",c);
fgetpos (stream,&pos);
fsetpos (stream,&pos);
c = fgetc (stream);
printf ("2nd character is %c\n",c);
fclose (stream);
}
return 0;
}
long int ftell ( FILE *  stream)
Parameters
streamFile pointer specifying the data stream.
Returns
status information:
  • file cursor position if successful.
  • -1L on error.

The function ftell reads the file cursor position.

The argument stream is a file pointer defining the data stream.

Note
  • On a 32-bit system, an object of type long int consists of 32-bits. Therefore, ftell operation is limited to the area of two gigabytes.

Code Example

#include <stdio.h> /* Standard I/O .h-file */
#include "rl_fs.h" /* FileSystem definitions */
void tst_ftell (void) {
long int fpos;
char line[80];
FILE *fin;
fin = fopen ("Counter.log","r");
if (fin != NULL) {
fgets (&line, sizeof (char), fin);
fpos = ftell (fin); // Get position after read operation
fclose (fin);
}
}
size_t fwrite ( const void *  ptr,
size_t  size,
size_t  nmemb,
FILE *  stream 
)
Parameters
ptrVoid pointer specifying the storage buffer.
sizeDefines the item size in bytes.
nmembDefines the number of items to write.
streamFile pointer specifying the data stream.
Returns
the number of members successfully written, which will be less than nmemb only if a write error is encountered.

The function fwrite writes items from a buffer to a data stream.

The argument ptr is a void pointer defining the items to write.

The argument size defines the size of the item to write.

The argument nmemb defines the number of times to write the item.

The argument stream is a file pointer defining the data stream to write to.

Code Example

#include <stdio.h> /* Standard I/O .h-file */
#include "rl_fs.h" /* FileSystem definitions */
void tst_fwrite (void) {
int count[10];
FILE *fout;
fout = fopen ("Counter.log","w");
if (fout != NULL) {
fwrite (&count[0], sizeof (int), 10, fout); // write an item 10 times to the file
fclose (fout);
}
}
int getc ( FILE *  stream)
Parameters
streamFile pointer specifying the data stream.
Returns
status information: -the next character from the input stream pointed to by stream.
  • EOF: If end-of-file is encountered or a read error occurs and no characters.

The function getc is equivalent to fgetc except that it may be implemented as an unsafe macro (stream may be evaluated more than once, so the argument should never be an expression with side-effects).

Code Example

#include <stdio.h> /* Standard I/O .h-file */
#include "rl_fs.h" /* FileSystem definitions */
void tst_getc (void) {
FILE *fin;
int ch;
fin = fopen ("Test.txt","r");
if (fin != NULL) {
// dump the character to a screen
while ((ch = getc (fin)) != EOF) {
putchar (ch);
}
fclose (fin);
}
}
int putc ( int  c,
FILE *  stream 
)
Parameters
cConstant character pointer specifying the string to write.
streamFile pointer specifying the data stream.
Returns
status information:
  • the character written if successful.
  • EOF: on error.

The function putc is equivalent to fputc except that it may be implemented as an unsafe macro (stream may be evaluated more than once, so the argument should never be an expression with side-effects).

Code Example

#include <stdio.h> /* Standard I/O .h-file */
#include "rl_fs.h" /* FileSystem definitions */
void tst_putc (void) {
FILE *fout;
int ch;
fout = fopen ("Test.txt","w");
if (fout != NULL) {
while ((ch = getchar ()) != EOF) {
putc (ch, fout); /* Copy the STDIN to a file */
}
fclose (fout);
}
}
void rewind ( FILE *  stream)
Parameters
streamFile pointer specifying the data stream.
Returns
no vlaue.

The function rewind positions the file cursor to the beginning of a data stream.

The argument stream is a file pointer defining the data stream. End-of-file and error indicators are cleared.

Code Example

#include <stdio.h> /* Standard I/O .h-file */
#include "rl_fs.h" /* FileSystem definitions */
void tst_rewind (void) {
char line[80];
FILE *fin;
fin = fopen ("Test.txt","r");
if (fin != NULL) {
if (fgets (&line, sizeof (line), fin) != NULL) {
rewind (fin); // move cursor to beginning of file
fgets (&line, sizeof (line), fin); // read first line again
}
fclose (fin);
}
}
void setbuf ( FILE *  stream,
char *  buf 
)
Parameters
streamFile pointer specifying the data stream.
bufArray pointer specifying the buffer for the stream.

Calling the function setbuf is equivalent to invoking setvbuf with _IOFBF as mode and BUFSIZ as size (when buf is not a null pointer), or equivalent to calling it with _IONBF as mode (when it is a null pointer). Also, setbuf does not return a value.

Code Example

#include <stdio.h> /* Standard I/O .h-file */
#include "rl_fs.h" /* FileSystem definitions */
void main (void)
{
char buffer[BUFSIZ];
FILE *stream1, *stream2;
stream1=fopen ("file.txt","w");
stream2=fopen ("file2.txt","a");
setbuf (stream1, buffer);
fputs ("Sent to a buffered stream",stream1);
fflush (stream1);
setbuf (stream2, NULL);
fputs ("Sent to an unbuffered stream",stream2);
fclose (stream1);
fclose (stream2);
return 0;
}
int setvbuf ( FILE *  stream,
char *  buf,
int  mode,
size_t  size 
)
Parameters
streamFile pointer specifying the data stream.
bufArray pointer specifying the buffer for the stream.
modeSpecifies how th stream will be buffered.
sizeSpecifies the size of the array.
Returns
status information:
  • 0 on success.
  • nonzero if invalid value was given for mode or size, or if the request can not be honoured.

The function setvbuf may be used after the stream pointed to by stream has been associated with an open file but before it is read or written.

The argument mode determines how stream will be buffered.

If buf is not the null pointer, the array it points to may be used instead of an automatically allocated buffer (the buffer must have a lifetime at least as great as the open stream, so the stream should be closed before a buffer that has automatic storage duration is deallocated upon block exit).

The argument size specifies the size of the array. The contents of the array at any time are indeterminate.

Stream buffers (blocks of data) are the link between I/O operations and the physical file that is represented by the stream: In case of output buffers, data is sent to the buffer until its maximum capacity is reached. Afterwards, it is flushed (i.e.: all data is written to the physical file at once and the buffer is cleared). Accordingly, input buffers are filled from the physical file, from which data is sent to the I/O operations until emptied, at which point new data is acquired from the file and the buffer being filled up again.

Stream buffers can be forced to flush by calling fflush. During normal operation, they are flushed by fclose and freopen, or when the program terminates without errors.

Code Example

#include <stdio.h> /* Standard I/O .h-file */
#include "rl_fs.h" /* FileSystem definitions */
void main (void)
{
FILE *stream;
stream=fopen ("file.txt","w");
setvbuf (stream, NULL, _IOFBF, 1024);
// Do some other file operations
fclose (stream);
return 0;
}
int ungetc ( int  c,
FILE *  stream 
)
Parameters
cConstant character pointer specifying the string to write.
streamFile pointer specifying the data stream.
Returns
status information:
  • the character pushed back after conversion.
  • EOF if the operation fails.

The function ungetc stores a character back into the data stream.

The argument c defines the character to store.

The argument stream is a file pointer defining the data stream to write to.

The function can be invoked only once between function calls that read from the data stream. Subsequent calls to ungetc fail with an EOF return value.

Code Example

#include <stdio.h> /* Standard I/O .h-file */
#include "rl_fs.h" /* FileSystem definitions */
void main (void) {
int c;
FILE *fin;
fin = fopen ("Test.txt","r");
if (fin != NULL) {
while ((c = fgetc (fin)) == ' '); // Skip leading spaces
ungetc (c, fin); // Unget the first non-space
ungetc (c, fin); // This call fails with EOF. File cursor is now positioned to a non-space character.
fclose (fin);
}
}
int vfprintf ( FILE *  stream,
const char *  format,
va_list  arg 
)
Parameters
streamFile pointer specifying the data stream.
formatPointer specifying the output format.
argA value identifying a variable argument list.

Equivalent to fprintf, with the variable argument list replaced by arg, which has been initialised by the va_start macro (and possibly subsequent va_arg calls). The vfprintf function does not invoke the va_end function.

Code Example

#include <stdio.h> /* Standard I/O .h-file */
#include "rl_fs.h" /* FileSystem definitions */
void WriteStream (FILE * stream, const char * format, ...)
{
va_list args;
va_start (args, format);
vfprintf (stream, format, args);
va_end (args);
}
int vfscanf ( FILE *  stream,
const char *  format,
va_list  arg 
)
Parameters
streamFile pointer specifying the data stream.
formatPointer specifying the formatting string.
argA value identifying a variable argument list.

The function vfscanf reads data from the stream and stores them according to the argument format at the locations pointed to by the elements in the arg argument list.

Code Example

#include <stdio.h> /* Standard I/O .h-file */
#include "rl_fs.h" /* FileSystem definitions */
void ReadStream (FILE * stream, const char * format, ...)
{
va_list args;
va_start (args, format);
vfscanf (stream, format, args);
va_end (args);
}