C file input/output

TheC programming languageprovides manystandard libraryfunctionsforfileinput and output.These functions make up the bulk of theC standard libraryheader<stdio.h>.The functionality descends from a "portable I/O package" written byMike LeskatBell Labsin the early 1970s,and officially became part of theUnixoperating system inVersion 7.

The I/O functionality of C is fairly low-level by modern standards; C abstracts all file operations into operations onstreamsofbytes,which may be "input streams" or "output streams". Unlike some earlier programming languages, C has no direct support forrandom-accessdata files; to read from a record in the middle of a file, the programmer must create a stream,seekto the middle of the file, and then read bytes in sequence from the stream.

The stream model of file I/O was popularized by Unix, which was developed concurrently with the C programming language itself. The vast majority of modern operating systems have inherited streams from Unix, and many languages in theC programming language familyhave inherited C's file I/O interface with few if any changes (for example,PHP).

Overview

This library uses what are called streams to operate with physical devices such as keyboards, printers, terminals or with any other type of files supported by the system. Streams are an abstraction to interact with these in a uniform way. All streams have similar properties independent of the individual characteristics of the physical media they are associated with.

Functions

Most of the C file input/output functions are defined in<stdio.h>(or in theC++headercstdio,which contains the standard C functionality but in thestdnamespace).

	Byte character	Wide character	Description
File access	fopen		Opens a file (with a non-Unicode filename on Windows and possible UTF-8 filename on Linux)
	freopen		Opens a different file with an existing stream
	fflush		Synchronizes an output stream with the actual file
	fclose		Closes a file
	setbuf		Sets the buffer for a file stream
	setvbuf		Sets the buffer and its size for a file stream
	fwide		Switches a file stream between wide-character I/O and narrow-character I/O
Direct input/output	fread		Reads from a file
	fwrite		Writes to a file
Unformatted input/output	fgetc getc	fgetwc getwc	Reads a byte/wchar_tfrom a file stream
	fgets	fgetws	Reads a byte/wchar_tline from a file stream
	fputc putc	fputwc putwc	Writes a byte/wchar_tto a file stream
	fputs	fputws	Writes a byte/wchar_tstring to a file stream
	getchar	getwchar	Reads a byte/wchar_tfrom stdin
	gets	—	Reads a byte string from stdin until a newline or end of file is encountered (deprecated in C99, removed from C11)
	putchar	putwchar	Writes a byte/wchar_tto stdout
	puts	—	Writes a byte string to stdout
	ungetc	ungetwc	Puts a byte/wchar_tback into a file stream
Formatted input/output	scanf fscanf sscanf	wscanf fwscanf swscanf	Reads formatted byte/wchar_tinput from stdin, a file stream or a buffer
	vscanf vfscanf vsscanf	vwscanf vfwscanf vswscanf	Reads formatted input byte/wchar_tfrom stdin, a file stream or a buffer using variable argument list
	printf fprintf sprintf snprintf	wprintf fwprintf swprintf	Prints formatted byte/wchar_toutput to stdout, a file stream or a buffer
	vprintf vfprintf vsprintf vsnprintf	vwprintf vfwprintf vswprintf	Prints formatted byte/wchar_toutput to stdout, a file stream, or a buffer using variable argument list
	perror	—	Writes a description of thecurrent errorto stderr
File positioning	ftell ftello		Returns the current file position indicator
	fseek fseeko		Moves the file position indicator to a specific location in a file
	fgetpos		Gets the file position indicator
	fsetpos		Moves the file position indicator to a specific location in a file
	rewind		Moves the file position indicator to the beginning in a file
Error handling	clearerr		Clears errors
	feof		Checks for the end-of-file
	ferror		Checks for a file error
Operations on files	remove		Erases a file
	rename		Renamesa file
	tmpfile		Returns a pointer to a temporary file
	tmpnam		Returns a unique filename

Constants

Constants defined in the<stdio.h>header include:

Name	Notes
EOF	A negative integer of typeintused to indicate end-of-file conditions
BUFSIZ	An integer which is the size of the buffer used by thesetbuf()function
FILENAME_MAX	The size of achararray which is large enough to store the name of any file that can be opened
FOPEN_MAX	The number of files that may be open simultaneously; will be at least eight
_IOFBF	An abbreviation for "input/output fully buffered"; it is an integer which may be passed to thesetvbuf()function to requestblock bufferedinput and output for an open stream
_IOLBF	An abbreviation for "input/output line buffered"; it is an integer which may be passed to thesetvbuf()function to requestline bufferedinput and output for an open stream
_IONBF	An abbreviation for "input/output not buffered"; it is an integer which may be passed to thesetvbuf()function to requestunbufferedinput and output for an open stream
L_tmpnam	The size of achararray which is large enough to store a temporary filename generated by thetmpnam()function
NULL	A macro expanding to thenull pointerconstant; that is, a constant representing a pointer value which is guaranteednotto be a valid address of an object in memory
SEEK_CUR	An integer which may be passed to thefseek()function to request positioning relative to the current file position
SEEK_END	An integer which may be passed to thefseek()function to request positioning relative to the end of the file
SEEK_SET	An integer which may be passed to thefseek()function to request positioning relative to the beginning of the file
TMP_MAX	The maximum number of unique filenames generable by thetmpnam()function; will be at least 25

Variables

Variables defined in the<stdio.h>header include:

Name	Notes
stdin	A pointer to aFILEwhich refers to the standard input stream, usually a keyboard.
stdout	A pointer to aFILEwhich refers to the standard output stream, usually a display terminal.
stderr	A pointer to aFILEwhich refers to the standard error stream, often a display terminal.

Member types

Data types defined in the<stdio.h>header include:

• FILE– also known as afilehandleor aFILE pointer,this is anopaque pointercontaining the information about a file or text stream needed to perform input or output operations on it, including:
  • platform-specific identifier of the associated I/O device, such as afile descriptor
  • the buffer
  • stream orientation indicator (unset, narrow, or wide)
  • stream buffering state indicator (unbuffered, line buffered, fully buffered)
  • I/O mode indicator (input stream, output stream, or update stream)
  • binary/text mode indicator
  • end-of-file indicator
  • error indicator
  • the current stream position and multibyte conversion state (an object of type mbstate_t)
  • reentrant lock (required as ofC11)
• fpos_t– a non-array type capable of uniquely identifying the position of every byte in a file and every conversion state that can occur in all supported multibyte character encodings
• size_t– anunsigned integertype which is the type of the result of thesizeofoperator.

Extensions

ThePOSIXstandard defines several extensions tostdioin its Base Definitions, among which are areadlinefunction that allocates memory, thefilenoandfdopenfunctions that establish the link betweenFILEobjects andfile descriptors,and a group of functions for creatingFILEobjects that refer to in-memory buffers.

Example

The following C program opens a binary file calledmyfile,reads five bytes from it, and then closes the file.

#include<stdio.h>
#include<stdlib.h>

intmain(void){
charbuffer[5];
FILE*fp=fopen("myfile","rb");

if(fp==NULL){
perror("Failed to open file\ "myfile\ "");
returnEXIT_FAILURE;
}

if(fread(buffer,1,5,fp)<5){
fclose(fp);
fputs("An error occurred while reading the file.\n",stderr);
returnEXIT_FAILURE;
}

fclose(fp);

printf("The bytes read were:");
for(inti=0;i<5;++i){
printf("%02X",buffer[i]);
}
putchar('\n');

returnEXIT_SUCCESS;
}

Alternatives to stdio

"Sfio" redirects here. For other uses of "SFIO", seeSFIO (disambiguation).

Several alternatives tostdiohave been developed. Among these is theC++iostreamlibrary, part of theISO C++ standard.ISO C++ still requires thestdiofunctionality.

Other alternatives include the Sfio(A Safe/Fast I/O Library) library fromAT&T Bell Laboratories.This library, introduced in 1991, aimed to avoid inconsistencies, unsafe practices and inefficiencies in the design ofstdio.Among its features is the possibility to insertcallback functionsinto a stream to customize the handling of data read from or written to the stream.It was released to the outside world in 1997, and the last release was 1 February 2005.

See also

• printf format string
• scanf format string

External links

• Media related toC file input/outputat Wikimedia Commons