C file input/output

Template:Short description Template:Use dmy dates Template:C Standard Library The C programming language provides many standard library functions for file input and output. These functions make up the bulk of the C standard library header Template:Mono.<ref>Template:Cite book</ref> The functionality descends from a "portable I/O package" written by Mike Lesk at Bell Labs in the early 1970s,<ref>Template:Cite book</ref> and officially became part of the Unix operating system in Version 7.<ref name="reader">Template:Cite tech report</ref>

The I/O functionality of C is fairly low-level by modern standards; C abstracts all file operations into operations on streams of bytes, which may be "input streams" or "output streams". Unlike some earlier programming languages, C has no direct support for random-access data files; to read from a record in the middle of a file, the programmer must create a stream, seek to 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 the C programming language family have 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.<ref>{{#invoke:citation/CS1|citation |CitationClass=web }}</ref>

Functions

Most of the C file input/output functions are defined in Template:Mono (or in the C++ header Template:Mono, which contains the standard C functionality but in the Template:Mono namespace).

	Byte character	Wide character	Description
File access	Template:Anchorfopen		Opens a file (with a non-Unicode filename on Windows and possible UTF-8 filename on Linux)
	Template:Anchorpopen		opens a process by creating a pipe, forking, and invoking the shell
	Template:Anchorfreopen		Opens a different file with an existing stream
	Template:Anchorfflush		Synchronizes an output stream with the actual file
	Template:Anchorfclose		Closes a file
	Template:Anchorpclose		closes a stream
	Template:Anchorsetbuf		Sets the buffer for a file stream
	Template:Anchorsetvbuf		Sets the buffer and its size for a file stream
	Template:Anchorfwide		Switches a file stream between wide-character I/O and narrow-character I/O
Direct input/output	Template:Anchorfread		Reads from a file
	Template:Anchorfwrite		Writes to a file
Unformatted input/output	Template:Anchorfgetc getc	Template:Anchorfgetwc getwc	Reads a byte/Template:Mono from a file stream
	Template:Anchorfgets	Template:Anchorfgetws	Reads a byte/Template:Mono line from a file stream
	Template:Anchorfputc putc	Template:Anchorfputwc putwc	Writes a byte/Template:Mono to a file stream
	Template:Anchorfputs	Template:Anchorfputws	Writes a byte/Template:Mono string to a file stream
	Template:Anchorgetchar	Template:Anchorgetwchar	Reads a byte/Template:Mono from stdin
	Template:Anchorgets	Template:N/a	Reads a byte string from stdin until a newline or end of file is encountered (deprecated in C99, removed from C11)
	Template:Anchorputchar	Template:Anchorputwchar	Writes a byte/Template:Mono to stdout
	Template:Anchorputs	Template:N/a	Writes a byte string to stdout
	Template:Anchorungetc	Template:Anchorungetwc	Puts a byte/Template:Mono back into a file stream
Formatted input/output	Template:Anchorscanf fscanf sscanf	Template:Anchorwscanf fwscanf swscanf	Reads formatted byte/Template:Mono input from stdin, a file stream or a buffer
	Template:Anchorvscanf vfscanf vsscanf	Template:Anchorvwscanf vfwscanf vswscanf	Reads formatted input byte/Template:Mono from stdin, a file stream or a buffer using variable argument list
	Template:Anchorprintf fprintf sprintf snprintf	Template:Anchorwprintf fwprintf swprintf	Prints formatted byte/Template:Mono output to stdout, a file stream or a buffer
	Template:Anchorvprintf vfprintf vsprintf vsnprintf	Template:Anchorvwprintf vfwprintf vswprintf	Prints formatted byte/Template:Mono output to stdout, a file stream, or a buffer using variable argument list
	Template:Anchorperror	Template:N/a	Writes a description of the current error to stderr
File positioning	Template:Anchorftell ftello		Returns the current file position indicator
	Template:Anchorfseek fseeko		Moves the file position indicator to a specific location in a file
	Template:Anchorfgetpos		Gets the file position indicator
	Template:Anchorfsetpos		Moves the file position indicator to a specific location in a file
	Template:Anchorrewind		Moves the file position indicator to the beginning in a file
Error handling	Template:Anchorclearerr		Clears errors
	Template:Anchorfeof		Checks for the end-of-file
	Template:Anchorferror		Checks for a file error
Operations on files	Template:Anchorremove		Erases a file
	Template:Anchorrename		Renames a file
	Template:Anchortmpfile		Returns a pointer to a temporary file
	Template:Anchortmpnam		Returns a unique filename

Constants

Constants defined in the Template:Mono header include:

Name	Notes
EOF	A negative integer of type Template:Mono used to indicate end-of-file conditions
Template:Anchor BUFSIZ	An integer which is the size of the buffer used by the Template:Mono function
FILENAME_MAX	The size of a Template:Mono array 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 the Template:Mono function to request block buffered input and output for an open stream
_IOLBF	An abbreviation for "input/output line buffered"; it is an integer which may be passed to the Template:Mono function to request line buffered input and output for an open stream
_IONBF	An abbreviation for "input/output not buffered"; it is an integer which may be passed to the Template:Mono function to request unbuffered input and output for an open stream
L_tmpnam	The size of a Template:Mono array which is large enough to store a temporary filename generated by the Template:Mono function
NULL	A macro expanding to the null pointer constant; that is, a constant representing a pointer value which is guaranteed not to be a valid address of an object in memory
SEEK_CUR	An integer which may be passed to the Template:Mono function to request positioning relative to the current file position
SEEK_END	An integer which may be passed to the Template:Mono function to request positioning relative to the end of the file
SEEK_SET	An integer which may be passed to the Template:Mono function to request positioning relative to the beginning of the file
TMP_MAX	The maximum number of unique filenames generable by the Template:Mono function; will be at least 25

Variables

File:Stdstreams-notitle.svg

Variables defined in the Template:Mono header include:

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

Member types

Data types defined in the Template:Mono header include:

• Template:Mono – also known as a Template:Anchorfile handle or a Template:Visible anchor, this is an opaque pointer containing 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 a file 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 of C11)
• Template:Mono – 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
• Template:Mono – an unsigned integer type which is the type of the result of the Template:Mono operator.

ExtensionsTemplate:Anchor

The POSIX standard defines several extensions to Template:Mono in its Base Definitions, among which are a Template:Mono function that allocates memory, the Template:Mono and Template:Mono functions that establish the link between Template:Mono objects and file descriptors, and a group of functions for creating Template:Mono objects that refer to in-memory buffers.<ref>Template:Man</ref>

Example

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

<syntaxhighlight lang="c">

1. include <stdio.h>
2. include <stdlib.h>

int main(void) {

   char buffer[5];
   FILE* fp = fopen("myfile", "rb");

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

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

   fclose(fp);

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

   return EXIT_SUCCESS;

} </syntaxhighlight>

Alternatives to stdioTemplate:Anchor

Several alternatives to Template:Mono have been developed. Among these is the [[Input/output (C++)|C++ Template:Mono]] library, part of the ISO C++ standard. ISO C++ still requires the Template:Mono functionality.

Other alternatives include the Sfio<ref>{{#invoke:citation/CS1|citation |CitationClass=web }}</ref> (A Safe/Fast I/O Library) library from AT&T Bell Laboratories. This library, introduced in 1991, aimed to avoid inconsistencies, unsafe practices and inefficiencies in the design of Template:Mono. Among its features is the possibility to insert callback functions into a stream to customize the handling of data read from or written to the stream.<ref>Template:Cite conference</ref> It was released to the outside world in 1997, and the last release was 1 February 2005.<ref>Template:Cite conference</ref>

See also

• printf format string
• scanf format string

External links

• Template:Commons category-inline