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:
"myfile" "yourfile.h" "d:something.xyz" "f:\\ djGPP\\ INClude\\ stdio.H" "COM1:" "lpt1:"
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: '
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:
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.:
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.