<tt>FILE *fopen(char *filename, char *mode)</tt>

Document: The C Standard Library

next int fgetc(FILE *stream)
up Input and Output: stdio.h
gif Input and Output: stdio.h

FILE *fopen(char *filename, char *mode)

fopen() is used to create a file pointer or stream, for subsequent input or output to a file. Thus, the return value from fopen() must normally be stored in a variable, so that it can then be used as an argument to other functions such as fgetc() etc.

filename is a string giving the name of the desired file. This should conform to the conventions of the "environment" or "operating system" under which the program will be running. Under DOS, file names consist, in general, of a device specifier (e.g., D: ), followed by a "path" identifying the desired subdirectory, followed by an individual file name proper. Directory and file names proper consist of a name part of up to 8 characters, followed by a period, followed by an "extension" part of up to three characters. DOS does not distinguish between upper and lower case anywhere in a file name. The directory separator character in DOS is the backslash '\' ; this is a rather unfortunate historical accident, as this character also has a special meaning in C strings, as an "escape" character. The nett effect is that, in representing a DOS file name in a C string constant, you must write the directory separator as a double backslash: \\ ; note that this actually only results in the internal storage of a single character within the string, when the program is compiled.

Examples of well formed filename arguments under DOS might be:

        "f:\\ djGPP\\ INClude\\ stdio.H"

Of course the filename argument, as with any of the other string arguments to be discussed, might equally be a string "variable" - the name of a char array which had previously been loaded with the desired file name (including the usual nul character as the string terminator: '\0 ').

mode is a string specifying the desired file "access mode" - i.e. what kind(s) of operations are going to be carried out on it. Two examples of legal values for this would be:

"r" : Open the file for reading.
"w" : Open the file for writing.

In general, fopen() will open a file for access either as a binary or a text file - but the default is implementation specific. In any case, regardless of the default, the type of access can be explicitly specified in the mode string by adding either a t or b character for text or binary respectively, e.g.:

"rt" : Open for reading as a text file.
"wb" : Open for writing as a binary file.

If the call to fopen() is successful, then the return value is simply the value of the created file pointer. However, if the call fails for any reason (e.g. trying to open a file on device "X:" when no such device is present on the machine) then the return value will be the special zero or null pointer value defined in C. stdio.h (and, indeed, several of the other header files) define the symbolic name NULL for this value. Thus, after a call to fopen() your program should always check the return value to see whether it is NULL - and take some appropriate action if so (e.g. issue a suitable message and call exit()). In any case, if the return value from fopen() is set to NULL then errno will also be set to some more specific error code.

Document: The C Standard Library

next int fgetc(FILE *stream)
up Input and Output: stdio.h
gif Input and Output: stdio.h

Fri Mar 29 14:35:38 GMT 1996