Opens a file by returning the address of a FILE structure.

    Format

      #include  <stdio.h>

      FILE *fopen  (const char *file_spec, const char *a_mode);
                   (ANSI C)

      FILE *fopen  (const char *file_spec, const char
                   *a_mode, . . . ); (DEC C Extension)

1  –  Arguments

 file_spec

    A character string containing a valid file specification.

 a_mode

    The access mode indicator. Use one of the following character
    strings: "r", "w", "a", "r+", "w+", "rb", "r+b", "rb+", "wb",
    "w+b", "wb+", "ab", "a+b", "ab+", or "a+".

    These access modes have the following effects:

    o  "r" opens an existing file for reading.

    o  "w" creates a new file, if necessary, and opens the file for
       writing. If the file exists, it creates a new file with the
       same name and a higher version number.

    o  "a" opens the file for append access. An existing file is
       positioned at the end-of-file, and data is written there. If
       the file does not exist, the C RTL creates it.

    The update access modes allow a file to be opened for both
    reading and writing. When used with existing files, "r+" and
    "a+" differ only in the initial positioning within the file. The
    modes are:

    o  "r+" opens an existing file for read update access. It is
       opened for reading, positioned first at the beginning-of-file,
       but writing is also allowed.

    o  "w+" opens a new file for write update access.

    o  "a+" opens a file for append update access. The file is first
       positioned at the end-of-file (writing). If the file does not
       exist, the C RTL creates it.

    o  "b" means binary access mode. In this case, no conversion of
       carriage-control information is attempted.

  . . .

    Optional file attribute arguments. The file attribute arguments
    are the same as those used in the creat function. For more
    information, see the creat function.

2  –  Description

    If a version of the file exists, a new file created with fopen
    inherits certain attributes from the existing file unless
    those attributes are specified in the fopen call. The following
    attributes are inherited:

       Record format
       Maximum record size
       Carriage control
       File protection

    If you specify a directory in the filename and it is a search
    list that contains an error, VSI C for OpenVMS Systems
    interprets it as a file open error.

    The file control block can be freed with the fclose function, or
    by default on normal program termination.

3  –  Return Values

    x                  File pointer.
    NULL               Indicates an error. The constant NULL is
                       defined in the <stdio.h> header file to be
                       the NULL pointer value. The function returns
                       NULL to signal the following errors:

                       o  File protection violations

                       o  Attempts to open a nonexistent file for
                          read access

                       o  Failure to open the specified file