Topic : Standart C Library for Unix
Author : James Rogers
Page : << Previous 2  Next >>
Go to page :

     fprintf(stderr,"Error closing stream.  (printed to standard error)\n");
        }  /* end if */

/* report success back to environment */
    return 0;

}  /* end main*/

The above simple program is an example of  opening a file, reading the file, and then closing the file while also using stdout, and stderr.  I cut and pasted the code to a vi session and then saved, compiled, and ran the program.

What follows is a quick summary of the file operations in the <stdio.h> library.  These are the operations that work directly with streams.

Opening Streams
Before a stream can be used you must associate the stream with some device or file.  This is called opening the stream.  Your program is asking for permission from the operating system to read or write to a device.  If you have the correct permissions, the file exists or you can create the file and no-one else has the file locked then the operating system allows you to open the file and gives you back an object that is the stream.  Using this object you can read and write to the stream and when you are done you can close the stream.
Let me discribe the format of the descriptions that you will see here and in the man pages.  The first entry is the type that is returned by the function call.  The second part is the function name itself and the third part is the list of variable types that the function takes for arguments.

Looking at the first line below we see that the fopen function takes two pointers to strings, one is a path to a file and the other is the open mode of the program.  The function will return a pointer to FILE type which is a complex object that is defined in the <stdio.h> library. So in order to accept the return type you must have declared a variable of type pointer to FILE, like the stream variable in the example above on line 9.  On line 13 of the example you can see where I call the function fopen with the static filename of "test" and a mode of "r" and then accept the return value into the stream object.

A stream can be opened by any of these three functions:

    FILE   *fopen( char *path, char *mode)
    FILE  *fdopen( int fildes, char *mode)
    FILE *freopen( char *path, char *mode, FILE *stream)

char *path is a pointer to a string with the filename in it.
char *mode is the mode of opening the file (table follows.)
int fildes is a file descriptor which has already been opened and whose mode matches.

You can get a file descriptor with the UNIX system function open.  Please note that a file descriptor is not a pointer to FILE.  You cannot close(stream), you must fclose(stream).  This is a very hard error to find if your compiler doesn't warn you about it.  If you are interested in Linux System calls type `man 2 intro`  for an introduction to the functions and what they do.
FILE *stream is an already existing stream.
These functions return a pointer to FILE type that represents the data stream or a NULL of type (FILE *)0 on any error condition.

fopen is used to open the given filename with the respective mode.  This is the function that is used the most to open files.

fdopen is used to assign a stream to a currently opened file descriptor.  The file descriptor mode and the fdopen mode must match.

freopen is normally used redirect stdin, stdout and stderr to file.  The stream that is given will be closed and a new stream opened to the given path with the given mode.

This table shows the modes and their results:

       open stream for  truncate create starting
mode   read    write    file     file   position
----   ----    -----    ----     ----   --------
"r"     y        n       n        n     beginning
"r+"    y        y       n        n     beginning
"w"     n        y       y        y     beginning
"w+"    y        y       y        y     beginning
"a"     n        y       n        y     end-of-file
"a+"    y        y       n        y     end-of-file

To read the first line, "r" will open a stream for read, the stream will not be opened for write, will not truncate the file to zero length, will not create the file if it doesn't already exist and will be positioned at the beginning of the stream.

Stream Flushing
Sometimes you want your program to ensure that what you have written to a file has actually gone to the disk and is not waiting in the buffer. Or you might want to throw out a lot of user input and get fresh input, for a game.  The following two functions are useful for emptying the streams buffers, though one just throws the data away while the other stores it safely on to the stream.
    int fflush(FILE *stream)
    int fpurge(FILE *stream)

FILE *stream is an already existing stream.

These functions return a 0 on success.  On a failure they return an EOF.

fflush is used to write out the buffers of the stream to a device or file.

fpurge is used to clear the buffers of unwritten or unread data that is in a buffer waiting.  I think of this as a destructive purge because it clears the read and write buffers by dumping the contents.

Closing Streams
When you are done with a stream you must clean up after your program.  When you close a stream the command ensures that the buffers are successfully written and that the stream is truly closed.  If you just exit a program without closing your files then more than likely the last few bytes that you wrote will be there.  But you won't know unless you check.  Also there is a limit to how many streams a single process can have open at one time. So if you keep on opening streams without closing the old streams you will use up system resources.  Only one command is used to close any stream.
    int fclose(FILE *stream)

FILE *stream is an already existing stream.

Returns a 0 on success, or an EOF otherwise.

fclose flushes the given streams buffers and then disassociates the stream from the pointer to FILE.

Renaming and Removing Files
These two commands work just like rm and mv, but without the options.  They are not recursive but your programs can be so watch that you don't accidentally build your own version of rm -rf / <<<by they way don't type this, it would delete your entire harddrive!!>>>

    int    remove(char *path)
    int    rename(char *oldpath, const char *newpath)

char *path, oldpath and newpath are all pointers to existing files.

Returns a 0 on success and a non-zero otherwise.

remove works just like rm to remove the file in the string pointed to by path.

rename works just like move to rename a file from oldpath to newpath, changing directories if need be.

Temporary Files
You can create your own temp files by using the following functions:
    FILE *tmpfile(void)

This command returns a pointer to a FILE of stream which is a temp file that magically goes away when your program is done running.  You never even

Page : << Previous 2  Next >>