CMPSC 311, C Standard I/O Library

CMPSC 311, Introduction to Systems Programming

The C Standard I/O Library

Reading

CP:AMA, Ch. 22, Input/Output; the Q&A is especially helpful
CS:APP

Sec. 10.8, Standard I/O
Sec. 10.9, Putting it Together: Which I/O Functions Should I Use?
Sec. 10.10, Summary

C:ARM, Ch. 15, Input/Output Facilities
APUE, Ch. 5, Standard I/O Library

#include <stdio.h>

See <wchar.h> for wide-character versions.

In C11, see <uchar.h>, and various sections of the Standard, for Unicode characters and strings. There is support for UTF-8, 16-bit Unicode, and 32-bit Unicode, mapped to the more flexible wide-character type.

Logical data streams

stream

Informally, a stream is any source of input or destination for output.

text streams

A text stream is an ordered sequence of characters composed into lines, each line consisting of zero or more characters plus a terminating newline character.
The expectation is that this is human-readable.

binary streams

A binary stream is an ordered sequence of characters that can transparently record internal data.
The expectation is that we don't care if this is human-readable or not, but
the transformation from data(1) to output stream to input stream to data(2) should yield data(1) = data(2).
If you wrote it, you can read it, and get the same result.

orientation

wide characters or not? wide-oriented or byte-oriented
see CP:AMA, p. 658

A stream is associated with an external file (or device) by opening a file, or by creating a new file.

Streams may be opened for reading, writing, or both.
Each stream has a file position indicator, which is initialized when the file is opened, and updated by subsequent read, write and seek requests.
Each stream has an error indicator, and an end-of-file indicator, which are set by operations that did not succeed.
The stream may also have a buffer in memory, as an interface to the underlying file or device.

Streams may be

unbuffered - characters are transmitted as soon as possible
line buffered - characters are transmitted when a newline character is encountered
fully buffered - characters are transmitted when the buffer is full

A file may be disassociated from a controlling stream by closing the file.

Output streams are flushed (any unwritten buffer contents are transmitted) before the stream is disassociated from the file.
When main() returns, or when exit() is called, all open files are closed.

Types

size_t

from <stddef.h>

result type of the sizeof operator, an unsigned integer

FILE

an object type capable of recording all the information needed to control a stream:

file position indicator,
pointer to associated buffer (if any),
error indicator (records whether a read/write error has occurred),
end-of-file indicator (records whether the end of the file has been reached),
etc.

We have an example later.

fpos_t

file position indicator (position within a file)

Macros

NULL

from <stddef.h>

used to indicate end-of-file, can be distinguished from a character value

stdin, stdout, stderr

expressions of type ‘‘pointer to FILE’’ that point to the FILE objects associated, respectively, with the standard input, output and error streams
The underlying file descriptors are 0, 1, 2 when the program starts.

BUFSIZ, _IOFBF, _IOLBF, _IONBF

see setbuf(), setvbuf()

FOPEN_MAX, FILENAME_MAX

see fopen()

SEEK_CUR, SEEK_END, SEEK_SET

used with fseek()

L_tmpnam, TMP_MAX

see tmpnam()

Functions

File access functions

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

open the file, associate a stream with it, return a pointer to the open stream, or return NULL

mode is one of

`"r"`	open text file for reading
`"w"`	open text file for writing; truncate to zero length or create
`"a"`	open or create text file for writing at end-of-file; append
`"rb"`	open binary file for reading
`"wb"`	open binary file for writing; truncate to zero length or create
`"ab"`	open or create binary file for writing at end-of-file; append
`"r+"`	open text file for update (reading and writing)
`"w+"`	open text file for update; truncate to zero length or create
`"a+"`	open or create text file for update, writing at end-of-file; append
`"r+b" or "rb+"`	open binary file for update (reading and writing)
`"w+b" or "wb+"`	open binary file for update; truncate to zero length or create
`"a+b" or "ab+"`	open or create binary file for update, writing at end-of-file; append

FOPEN_MAX

the minimum number of files that the implementation guarantees can be open simultaneously (at least 8)
on Mac OS X, 20; on Solaris, 20 or 60; on Linux, 16
compare to OPEN_MAX, defined by Posix, in <limits.h>

FILENAME_MAX

size needed for an array of char large enough to hold the longest file name string that the implementation guarantees can be opened

int fclose(FILE *stream);

disassociate the stream from its underlying file, close the file, and return 0, or return EOF

int fflush(FILE *stream);

transmit the stream's buffer contents, if any

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

close and reopen a stream
for example,

to associate a different file with the stream
to change the mode of a stream that is already open (C99)

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

obsolete, use setvbuf() instead

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

modify the stream's buffer properties, or supply your own buffer
BUFSIZ is an appropriate buffer size, at least 256
_IOFBF, _IOLBF, _IONBF are used as mode values for setvbuf() to indicate the buffering style (fully-buffered, line-buffered, unbuffered)

Formatted input/output functions

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

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

int snprintf(char * restrict s, size_t n, const char * restrict format, ...);
int sprintf(char * restrict s, const char * restrict format, ...);
int sscanf(const char * restrict s, const char * restrict format, ...);

int vfprintf(FILE * restrict stream, const char * restrict format, va_list arg);
int vfscanf(FILE * restrict stream, const char * restrict format, va_list arg);
int vprintf(const char * restrict format, va_list arg);
int vscanf(const char * restrict format, va_list arg);
int vsnprintf(char * restrict s, size_t n, const char * restrict format, va_list arg);
int vsprintf(char * restrict s, const char * restrict format, va_list arg);
int vsscanf(const char * restrict s, const char * restrict format, va_list arg);

Character input/output functions

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

The fgets function reads at most one less than the number of characters specified by n from the stream pointed to by stream into the array pointed to by s. No additional characters are read after a new-line character (which is retained) or after end-of-file. A null character is written immediately after the last character read into the array.
The fgets function returns s if successful. If end-of-file is encountered and no characters have been read into the array, the contents of the array remain unchanged and a null pointer is returned. If a read error occurs during the operation, the array contents are indeterminate and a null pointer is returned.
An end-of-file and a read error can be distinguished by use of the feof() and ferror() functions.

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

getc() is probably a macro. fgetc() is definitely a function.

int getchar(void);

getchar() is the same as getc(stdin)

char *gets(char *s);

Do not use this function. Do you understand why?

int putc(int c, FILE *stream);

putc() is probably a macro. fputc() is definitely a function.

int putchar(int c);

putchar(c) is the same as putc((c), stdout)

int puts(const char *s);

Output to stdout, followed by a newline character.

int ungetc(int c, FILE *stream);

Push c back to the stream's buffer, and clear the end-of-file indicator.
Not required to work more than once before the next read operation.

Direct input/output functions (block I/O)

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

can be used for entire arrays, or for single items
if s is an object of struct type, for example, fwrite(&s, sizeof(s), 1, fp);

File positioning functions

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

move the file position indicator, to the position that is offset bytes from the beginning of the file (whence = SEEK_SET), from the current position (whence = SEEK_CUR), from the end of the file (whence = SEEK_END), or from elsewhere (whence = any value obtained from ftell())
clears end-of-file indicator

long int ftell(FILE *stream);

current value of the file position indicator, but it might not mean what you think it does (see CP:AMA, pp. 573-4)

void rewind(FILE *stream);

almost the same as (void) fseek(stream, 0L, SEEK_SET)
also clears error indicator

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

C functions, for large files, more portable than ftell(), fseek()
fpos_t file_position; fgetpos(fp, &file_position); // save current position // do some reads and writes fsetpos(fp, &file_position); // return to previous position

int fseeko(FILE *stream, off_t offset, int whence);
off_t ftello(FILE *stream);

POSIX functions, for large files; off_t may be 32 or 64 bits

Error-handling functions

int feof(FILE *stream);

inspect the stream's end-of-file indicator

int ferror(FILE *stream);

inspect the stream's error indicator

void clearerr(FILE *stream);

clear the stream's error indicator and end-of-file indicator

void perror(const char *s);

print an error message, using errno

Operations on files

int remove(const char *filename);
int rename(const char *old, const char *new);
FILE *tmpfile(void);

create and open a temporary binary file ("wb+" mode); will be removed when closed

char *tmpnam(char *s);

generate a string that is a unique valid file name
TMP_MAX

maximum number of unique file names that can be generated by tmpnam() (at least 25)

L_tmpnam

size needed for an array of char large enough to hold a temporary file name string generated by tmpnam()

Sample usage, from a simple command shell

#include <stdio.h>

FILE *infile; char *infile_name;

if (... should take input from stdin ...) { infile = stdin; infile_name = "[stdin]"; } else { infile_name = argv[... something ...]; /* also use strdup()? */ infile = fopen(infile_name, "r"); /* read-only */ if (infile == NULL) { fprintf(stderr, "%s: cannot open file %s: %s\n", program_name, infile_name, strerror(errno)); exit(EXIT_FAILURE); /* or something less brutal */ } }


        char buffer[128];

while (fgets(buffer, sizeof(buffer), infile) != NULL) { /* Note that buffer has a newline at the end if the input line * was short enough to fit. * NULL indicates end-of-file or error. * Is line-too-long an error? */ if (verbose) printf("%s: have: %s", program_name, buffer);

/* do the work */ }

/* No more input. Was it an input error or just end-of-file? */ if (feof(infile)) { printf("%s: end of input\n", program_name); } if (ferror(infile)) { printf("%s: error reading input\n", program_name); }
if (fclose(infile) != 0)
{ fprintf(stderr, "%s: cannot close file %s: %s\n", program_name, infile_name, strerror(errno)); exit(EXIT_FAILURE); /* or something less brutal */ }

Sample design, read one or more files, line-by-line



      

      int read_file(char *file);

      int read_line(FILE *fileptr);

        // return 0 for success, -1 for failure

      

      

      

      if (read_file(input_file_name) == -1)

        {

          printf("read_file() failed: %s\n",
      input_file_name);

        }

      

      

      

      int read_file(char *file)

      { 

        if (file == NULL)

          {

printf("read_file()
      failed: NULL arg\n");

      return -1; 

          }

      

        FILE *input = fopen(file, "r");

      

        if (input == NULL)

          {

            printf("read_file() failed: %s not
      opened:
      %s\n",

              file,
      strerror(errno));

            return -1;

          }

        

        while (read_line(input) == 0) ;

       

        fclose(input);

      

        return 0;

      }

int read_line(FILE *fileptr)

      {

        if (fileptr == NULL)

          { return -1; }

      

        char buffer[1024];

if (fgets(buffer, sizeof(buffer),
        fileptr) ==
        NULL)

            {

              return -1;  // EOF or error

            }

  ... do something with buffer

      

        return 0;

      }

What should you do if there is an input line longer than 1024 characters?

Excerpt from OpenSolaris, <stdio.h>, the stripped-down stand-alone subset of the C library, where everything is really unbuffered

typedef struct {
  unsigned char	_flag; 		/* state of the stream */
  int		_file;		/* file descriptor */
  ssize_t	_len;		/* total len of file */
  ssize_t	_offset;	/* offset within the file */
  char		_name[256];	/* name of the file (for debugging) */
} FILE;

Excerpt from OpenSolaris, <stdio.h> (iob = I/O Buffer)

#define	BUFSIZ	1024
#define _SBFSIZ	8

extern	struct	_iobuf {
	int	_cnt;
	unsigned char *_ptr;
	unsigned char *_base;
	int	_bufsiz;
	short	_flag;
	char	_file;		/* should be short */
} _iob[];

#define _IOFBF	 0
#define	_IOREAD	 01
#define	_IOWRT	 02
#define	_IONBF	 04
#define	_IOMYBUF 010
#define	_IOEOF	 020
#define	_IOERR	 040
#define	_IOSTRG	 0100
#define	_IOLBF	 0200
#define	_IORW	 0400

#define	NULL	0
#define	FILE	struct _iobuf
#define	EOF	(-1)

#define	stdin	(&_iob[0])
#define	stdout	(&_iob[1])
#define	stderr	(&_iob[2])

#define	getc(p)		(--(p)->_cnt >= 0 ? ((int)*(p)->_ptr++) : _filbuf(p))

#define putc(x, p)	(--(p)->_cnt >= 0 ?\
	(int)(*(p)->_ptr++ = (unsigned char)(x)) :\
	(((p)->_flag & _IOLBF) && -(p)->_cnt < (p)->_bufsiz ?\
		((*(p)->_ptr = (unsigned char)(x)) != '\n' ?\
			(int)(*(p)->_ptr++) :\
			_flsbuf(*(unsigned char *)(p)->_ptr, p)) :\
		_flsbuf((unsigned char)(x), p)))

Elsewhere,

/* The routine _flsbuf may or may not actually flush the output buffer.  If
 * the file is line-buffered, the fact that iop->_cnt has run below zero
 * is meaningless: it is always kept below zero so that invocations of putc
 * will consistently give control to _flsbuf, even if the buffer is far from
 * full.  _flsbuf, on seeing the "line-buffered" flag, determines whether the
 * buffer is actually full by comparing iop->_ptr to the end of the buffer
 * iop->_base + iop->_bufsiz.  If it is full, or if an output line is
 * completed (with a newline), the buffer is flushed.  (Note: the character
 * argument to _flsbuf is not flushed with the current buffer if the buffer
 * is actually full -- it goes into the buffer after flushing.)
 */

extern int _flsbuf(unsigned char c, FILE *iop);

Translated to "readable C",

int putc(int x, FILE *p)
{
  unsigned char xx = (unsigned char)(x);

  if (--p->_cnt >= 0)
    { return (int)(*p->_ptr++ = xx); }
  else
    {
      if ((p->_flag & _IOLBF) && -p->_cnt < p->_bufsiz)
        {
          if ((*p->_ptr = xx) != '\n')
            { return (int)(*p->_ptr++); }
          else
            { return _flsbuf(*(unsigned char *)p->_ptr, p); }
        }
      else
        { return _flsbuf(xx, p); }
    }
}

Excerpt from Mac OS X,

<stdio.h>

      

      /* stdio buffers */

      struct __sbuf {

              unsigned
      char  
      *_base;

             
int            
      _size;

      };

      

      /* hold a buncha junk that would grow the ABI */

      struct __sFILEX;

      

      typedef struct __sFILE {

        unsigned char *_p;      /* current
      position in (some) buffer */

        int    
      _r;            
/*
read
space
left
      for getc() */

        int    
      _w;            
/*
write
space
left
      for putc() */

        short  
      _flags;         /* flags,
      below; this FILE is free if 0 */

        short  
      _file;          /*
      fileno,
      if Unix descriptor, else -1 */

        struct  __sbuf _bf;     /* the
      buffer
      (at least 1 byte, if !NULL) */

        int    
      _lbfsize;       /* 0 or -_bf._size,
      for
      inline putc */

      

        /* operations */

        void   
      *_cookie;       /* cookie passed to
      io
      functions */

        int     (*_close)(void *);

        int     (*_read) (void *, char *, int);

        fpos_t  (*_seek) (void *, fpos_t, int);

        int     (*_write)(void *, const char *,
      int);

      

        /* separate buffer for long sequences of ungetc() */

        struct  __sbuf _ub;     /* ungetc
      buffer */

        struct __sFILEX *_extra; /* additions to FILE to not break
      ABI */

        int    
      _ur;           
/*
      saved _r when _r is counting ungetc data */

      

        /* tricks to meet minimum requirements even when malloc()
      fails
      */

        unsigned char _ubuf[3]; /* guarantee an ungetc() buffer */

        unsigned char _nbuf[1]; /* guarantee a getc() buffer */

      

        /* separate buffer for fgetln() when line crosses buffer
      boundary */

        struct  __sbuf _lb;     /* buffer
      for
      fgetln() */

      

        /* Unix stdio files get aligned to block boundaries on
      fseek() */

        int    
      _blksize;       /* stat.st_blksize
      (may
      be != _bf._size) */

        fpos_t 
      _offset;       
      /* current lseek offset (see WARNING) */

      } FILE;

This should now make sense to you:

/*  Functions internal to the implementation. */

      int  __srget(FILE *);

      int  __swbuf(int, FILE *);

#define __sgetc(p) (--(p)->_r < 0 ? __srget(p) :
      (int)(*(p)->_p++))

      

      static __inline int __sputc(int _c, FILE *_p)

      {

        if (--_p->_w >= 0 || (_p->_w >= _p->_lbfsize
      && (char)_c != '\n'))

          return (*_p->_p++ = _c);

        else

          return (__swbuf(_c, _p));

      }

Last revised, 18 Feb. 2013