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. Within the Cygwin environment file names consist, in general, of a device specifier (e.g., "//h" ), followed by a "path" identifying the desired subdirectory, followed by an individual file name proper. On Microsoft platforms there is generally no distinction between upper and lower case characters anywhere in a file name; whereas on Unix platforms they are considered to be distinct. The directory separator character in the Cygwin environment is the slash '/' character.

Examples of well formed filename arguments under Cygwin might be:

    "myfile"
    "yourfile.h"
    "//h/something.xyz"
    "//f/NetscapeNT/bookmarks.html"

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.