Lab 1 Notes: Standard I/O Library

These notes are based on Chap. 5 of "Advanced Programming in the UNIX Environment" by W. Richard Stevens. These notes are only a quick summary, and are not intended to replace what is written in the book.

5.1) Intro
5.2) Streams and FILE Objects
5.3) Standard Input, Standard Output, and Standard Error
5.4) Buffering
5.5) Opening a Stream
5.6) Reading and Writing a Stream
5.7) Line-at-a-Time I/O
5.8) Standard I/O Efficiency
5.9) Binary I/O
5.10) Positioning a Stream
5.11) Formatted I/O
5.12) Implementation Details
5.13) Temporary Files
Appendix: Examples

5.1) Introduction

There are 2 key was to do I/O:

Using file descriptors
Using file streams (as defined by standard I/O library). This is the topic of these notes.

5.2) Streams and FILE Objects

To open a stream use the standard I/O function fopen, which returns a pointer to a FILE object.
Application software should never need to examine a FILE object
To reference the stream, we pass a FILE pointer as an argument to each standard I/O function

5.3) Standard Input, Standard Output, and Standard Error

3 streams are predefined & automatically available: standard input, standard output, standard error
These streams can be referenced through the predefined file pointers: stdin, stdout, stderr (all three are defined in the stdio.h header)

For example, the following two programs are equivalent:

#include <stdio.h>             
                                     
void main() {                        
                                     
    /* default is standard output */ 
    printf("Hello world\n");         
}                                    


#include <stdio.h>

void main() {

    /* stating file stream explicitly */
    fprintf(stdout, "Hello world\n");
}

5.4) Buffering

When you use the standard I/O, sometimes the data is buffered before it is delivered to it's destination
The purpose of buffering is to improve efficiency by reducing the number of read/write system calls
3 Types of buffering:
1. Fully Buffered - I/O happens when the buffer is full
2. Line Buffered - I/O happens when either a newline character is encountered, or the buffer becomes full
3. Unbuffered - I/O happens immediately. No buffering is used.
Flushing = the writing of a standard I/O buffer
Buffers can be explicitly flushed by using the fflush system call
By default,
1. Standard error is always unbuffered
2. All other streams are line buffered if they refer to a terminal device; otherwise they are fully buffered

We can change the buffering by calling the following function:

#include <stdio.h>

/* Returns: 0 if OK, nonzero on error */
int setvbuf(FILE *fp, char *buf, int mode, size_t size);

The setvbuf function must be called after the stream has been opened, but before any other operation is performed on the stream
With setvbufwe specify exactly what type of buffering we want
To enable buffering:
- mode can be either _IOFBF (for fully buffered) or _IOLBF (for line buffered)
- set buf and size to NULL (you can optionally use buf and size to explicitly specify the buffer and its size. See p.124)
To disable buffering:
- set mode to _IONBF (for unbuffered)
- set buf and size to NULL (these arguments get ignored)

5.5) Opening a Stream

The following three functions open a standard I/O stream:

#include <stdio.h>

/* All three return: file pointer if OK, NULL on error */
FILE *fopen  (const char *pathname, const char *type);
FILE *freopen(const char *pathname, const char *type, FILE *fp);
FILE *fdopen (int   fileDescriptor, const char *type);

fopen opens a specified file
freopen opens a specified file on a specified stream, closing the stream first, if it is already open. This function is typically used to open a specified file as one of the predefined streams: standard input, standard output, or standard error
fdopen takes an existing file descriptor (which we could obtain from the open, dup, dup2, fcntl, or pipe functions) and associates a standard I/O stream with a descriptor. This function is often used with descriptors that are returned by the functions that create pipes and network communication channels. Since these special types of files cannot be opened with the standard I/O fopen function, we have to call the device-specific function to obtain a file descriptor, and then associate this descriptor with a standard I/O stream using fdopen.
the opposite of fdopen is fileno (see Section 5.12), which returns the file descriptor associated with a stream.

the type argument can be set to:

r	open for reading
w	truncate to 0 length or create for writing
a	append; open for writing at end of file, or create for writing
r+	open for reading and writing
w+	truncate to 0 length or create for reading and writing
a+	open or create for reading and writing at end of file

An open stream is closed by calling fclose:

#include <stdio.h>

/* Returns: 0 if OK, EOF on error */
int fclose (FILE *fp);

Any buffered output data is flushed before the file is closed. Any input data that may be buffered is discarded.
When a process terminates normally, either by calling the exit function directly, or by returning from the main function, all standard I/O streams with unwritten buffered data are flushed, and all open standard I/O streams are closed.

5.6) Reading and Writing a Stream

Formatted I/O (ie. fprintf and fscanf) are described in section 5.11. This section describe non-formatted I/O.

The following are some important functions:

#include <stdio.h>

int fgetc (FILE *fp);
/*
 * fgets is used to read one character at a time.
 *
 * Returns: next character if OK, EOF on end of file 
 */

int fputc (int c, FILE *fp);
/*
 * fputc writes one character at a time
 *
 * Returns: c is OK, EOF on error
 */

char *fgets (char *buf, int n, FILE *fp);
/*
 * fgets reads a line-at-a-time.  We have to specify 
 * the size of the buffer, n.  This function reads
 * up through and including the next newline, but no more
 * than n-1 characters, into the buffer.  The buffer
 * is terminated with a null byte.  If the line, including the
 * terminating newline, is longer than n-1, then only
 * a partial line is returned, but the buffer is always 
 * null terminated.  Another call to fgets will read
 * what follows on the line
 * 
 * Returns: buf if OK, NULL on end of file or error
 */

int fputs (const char *str, FILE *fp);
/*
 * fputs is generally used to write a line-at-a-time.
 * The function fputs writes a null terminated string to the
 * specified stream.  The null byte at the end is not written.
 * Note that this need not be a line-at-a-time output, since the
 * string need not contain a newline as the last nonnull character
 * 
 * Returns: nonnegative value if OK, EOF on error
 */

int ferror (FILE *fp);
int feof   (FILE *fp);
/*
 * You'll notice that with fgetc and fgets that the same value is
 * returned regardless whether an error occurs or the 
 * end of file is reached.  To distinguish between the two, we 
 * must call either ferror or feof.
 * 
 * Both return: nonzero (true) if condition is true, 0 (false) otherwise 
 */

5.7) Line-at-a-Time I/O

set fgets and fputs, described in the previous section

5.8) Standard I/O Efficiency

The standard I/O library is not much slower than calling the read and write functions directly (see p.131-133 for details)
For most nontrivial applications, the largest amount of the user CPU time is taken by the application and not by the standard I/O routines

5.9) Binary I/O

These are useful for reading/writing parts of a binary array, and also for reading/writing structures. If we tried to use getc or putc, if would be more work. If we tried using fputs it might stop when it hits a null byte. If we tried using fgets then it would stop if there are null bytes or newlines.

The read/write routines:

#include <stdio.h>

/*
 * Both return: number of objects read or written 
 */
size_t fread  (void *ptr,       size_t size, size_t nobj, FILE *fp);
size_t fwrite (const void *ptr, size_t size, size_t nobj, FILE *fp);

Example: to write elements 2 through 5 of a floating point array:

    float data[10];

    /* here we specify size = the size of each element of the array,
     *             and nobj = the number of elements in the array
     */
    if (fwrite(&data[2], sizeof(float), 4, fp) != 4)
        fprintf(stderr, "fwrite error!");

Example: to write a structure:

    struct {
        short  count;
        long   total;
        char   name [NAMESIZE];
    } item

    /* here we specify size = the size of the structurre
     *             and nobj = 1 (the # of objects to write)
     */
    if (fwrite(&item, sizeof(item), 1, fp) != 1)
        fprintf(stderr, "fwrite error!");

The problem with binary I/O is that it can only be (reliably) used to read data that has been written with the same system.

5.10) Positioning a Stream

There are two ways to position a standard I/O stream:

Using ftell and fseek, described by:

#include <stdio.h>

long ftell (FILE *fp);
/*
 * gets the current file position relative to the beginning
 * of the file
 *
 * Returns: current file position indicator if OK, -1L on error
 */

int fseek (FILE *fp, long offset, int whence);
/* 
 * For binary files:
 *     offset = byte offset, relative to whence
 *     whence = { SEEK_SET means from the beginning of a file,
 *                SEEK_CUR means from the current file position,
 *                SEEK_END means from the end of file }
 *
 * For text files:
 *     offset = { 0 (meaning rewind to beginning), 
 *                or a value previously returned by ftell
 *                for that file }
 *     whence = SEEK_SET
 *
 * Returns: 0 if OK, nonzero on error
 */

void rewind (FILE *fp);
/*
 * Rewinds to the beginning of a file.  Works with both binary
 * and text files
 */

Using fgetpos and fsetpos, described by:

#include <stdio.h>

/*
 * fgetpos stores the current value of the file's position 
 * indicator in the object pointed to by pos.  This value
 * can be used in a later call to fsetpos to reposition 
 * the stream to that location
 * 
 * Note: they introduce a new abstract data type, fpos_t, that
 *       records a file's position
 *
 * Both return: 0 if OK, nonzero on error 
 */
int fgetpos (FILE *fp, fpos_t *pos);
int fsetpos (FILE *fp, const fpos_t *pos);

5.11) Formatted I/O

    #include <stdio.h>

    int printf (const char *format, ...);
    /* 
     * printf writes to the standard output. 
     *
     * Returns: the number of characters output if OK, 
     *          negative value if output error
     */
  
    int fprintf (FILE *fp, const char *format, ...);
    /*
     * fprintf writes to the specified stream.
     * 
     * Returns: the number of characters output if OK, 
     *          negative value if output error
     */

    int sprintf (char *buf, const char *format, ...);
    /* 
     * sprintf writes to the character array buf.
     * sprintf automatically appends a null byte at the end of
     * the array, but this null byte is no included in the
     * return value.
     *
     * Returns: the number of characters stored in the array
     */

5.12) Implementation Details

Each standard I/O stream has an associated file descriptor, which can be obtained using:

#include <stdio.h>

/* Returns: the file descriptor associated with the stream */
int fileno (FILE *fp);

5.13) Temporary Files

There are two advantages for using temporary files:
1. The file is automatically assigned a unique name, so it won't overwrite any previously existing file
2. The file is automatically removed when it is closed (or on program termination)

The function syntax:

#include <stdio.h>

/* Returns: file pointer to a unique file if OK, NULL on error */
FILE *tmpfile (void);