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

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

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

clearerr()

void clearerr

(

FILE *

stream

)

Clear end-of-file and error indicators.

Parameters

stream

File pointer specifying the data stream.

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;
}

fclose()

int fclose

(

FILE *

stream

)

Close file stream.

Parameters

stream

File 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) == 0) {
      printf ("File closed!\n");
    }
    else  {
      printf ("File could not be closed!\n");
    }
  }
}

feof()

int feof

(

FILE *

stream

)

Report whether end of stream has been reached.

Parameters

stream

File 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);
  }
}

ferror()

int ferror

(

FILE *

stream

)

Report whether there is an error in file stream.

Parameters

stream

File 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);
  }
}

fflush()

int fflush

(

FILE *

stream

)

Flush file stream.

Parameters

stream

File 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);
  }
}

fgetc()

int fgetc

(

FILE *

stream

)

Read character from file stream.

Parameters

stream

File 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);
  }
}

fgetpos()

int fgetpos	(	FILE *	stream,
		fpos_t *	pos
	)

Store current value of file position indicator.

Parameters

stream	File pointer specifying the data stream.
pos	Pointer 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;
}

fgets()

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

Read string from file stream.

Parameters

s	Pointer specifying the storage buffer.
n	Specifies the number of characters to read.
stream	File 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);
  }
}

fopen()

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

Open file stream.

Parameters

filename	File pointer specifying the file to open.
mode	Pointer 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:

Mode	Description
"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!

- Multiple active file handles (FILE *) per file are allowed only for files opened in read mode.

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);
  }
}

fprintf()

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

Write formatted string to file stream.

Parameters

stream	File pointer specifying the data stream.
format	Pointer 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);
  }
}

fputc()

int fputc	(	int	c,
		FILE *	stream
	)

Write character to file stream.

Parameters

c	Integer value specifying the character to write.
stream	File 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);
  }
}

fputs()

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

Write string to file stream.

Parameters

s	Constant character pointer specifying the string to write.
stream	File 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);
  }
}

fread()

size_t fread	(	void *	ptr,
		size_t	size,
		size_t	nmemb,
		FILE *	stream
	)

Read number of bytes from file stream.

Parameters

ptr	Void pointer specifying the storage buffer.
size	Defines the item size in bytes.
nmemb	Defines the number of items to read.
stream	File 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);
  }
}

freopen()

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

Reopen file stream.

Parameters

filename	File pointer specifying the file to open.
mode	Pointer defining the access type.
stream	File 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);
}

fscanf()

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

Read formatted string from file stream.

Parameters

stream	File pointer specifying the data stream.
format	Pointer 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);
  }
}

fseek()

int fseek	(	FILE *	stream,
		long int	offset,
		int	whence
	)

Move file stream's in-file pointer to new location.

Parameters

stream	File pointer specifying the data stream.
offset	File Long integer value specifying the number of bytes to move.
whence	Integer 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 Value	Description
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);
  }
}

fsetpos()

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

Set file position indicator.

Parameters

stream	File pointer specifying the data stream.
pos	Pointer 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;
}

ftell()

long int ftell

(

FILE *

stream

)

Get current location of stream's in-file pointer.

Parameters

stream

File 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);
  }
}

fwrite()

size_t fwrite	(	const void *	ptr,
		size_t	size,
		size_t	nmemb,
		FILE *	stream
	)

Write number of bytes to file stream.

Parameters

ptr	Void pointer specifying the storage buffer.
size	Defines the item size in bytes.
nmemb	Defines the number of items to write.
stream	File 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);
  }
}

getc()

int getc

(

FILE *

stream

)

Read character from file stream (unsafe).

Parameters

stream

File 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);
  }
}

putc()

int putc	(	int	c,
		FILE *	stream
	)

Write character to file stream (unsafe).

Parameters

c	Constant character pointer specifying the string to write.
stream	File 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);
  }
}

rewind()

void rewind

(

FILE *

stream

)

Move file stream's in-file pointer to beginning of file.

Parameters

stream

File pointer specifying the data stream.

The function rewinds positions of 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);
  }
}

setbuf()

void setbuf	(	FILE *	stream,
		char *	buf
	)

Buffer stream.

Parameters

stream	File pointer specifying the data stream.
buf	Array 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;
}

setvbuf()

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

Buffer stream.

Parameters

stream	File pointer specifying the data stream.
buf	Array pointer specifying the buffer for the stream.
mode	Specifies how th stream will be buffered.
size	Specifies 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;
}

ungetc()

int ungetc	(	int	c,
		FILE *	stream
	)

Stores a character into an input file stream.

Parameters

c	Constant character pointer specifying the string to write.
stream	File 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);
  }
}

vfprintf()

int vfprintf	(	FILE *	stream,
		const char *	format,
		va_list	arg
	)

Parameters

stream	File pointer specifying the data stream.
format	Pointer specifying the output format.
arg	A value identifying a variable argument list.

Equivalent to fprintf, with the variable argument list replaced by arg, which has been initialized 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);
}

vfscanf()

int vfscanf	(	FILE *	stream,
		const char *	format,
		va_list	arg
	)

Parameters

stream	File pointer specifying the data stream.
format	Pointer specifying the formatting string.
arg	A 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);
}