NAME

       fopen - open a stream

SYNOPSIS

       #include <stdio.h>

       FILE *fopen(const char *restrict filename, const char *restrict mode);

DESCRIPTION

       The  fopen()  function  shall  open  the  file  whose pathname is the string pointed to by
       filename, and associates a stream with it.

       The mode argument points to a string. If the string is one  of  the  following,  the  file
       shall be opened in the indicated mode. Otherwise, the behavior is undefined.

       r or rb
              Open file for reading.

       w or wb
              Truncate to zero length or create file for writing.

       a or ab
              Append; open or create file for writing at end-of-file.

       r+ or rb+ or r+b
              Open file for update (reading and writing).

       w+ or wb+ or w+b
              Truncate to zero length or create file for update.

       a+ or ab+ or a+b
              Append; open or create file for update, writing at end-of-file.

       The  character  'b'  shall  have no effect, but is allowed for ISO C standard conformance.
       Opening a file with read mode (r as the first character in the mode argument)  shall  fail
       if the file does not exist or cannot be read.

       Opening  a  file  with  append  mode (a as the first character in the mode argument) shall
       cause all subsequent writes to the file to be forced  to  the  then  current  end-of-file,
       regardless of intervening calls to fseek().

       When  a file is opened with update mode ( '+' as the second or third character in the mode
       argument), both input and output may be performed on the associated stream.  However,  the
       application  shall  ensure  that  output  is  not  directly  followed  by input without an
       intervening call to fflush() or to a file positioning function (  fseek(),  fsetpos(),  or
       rewind()),  and  input is not directly followed by output without an intervening call to a
       file positioning function, unless the input operation encounters end-of-file.

       When opened, a stream is fully buffered if and only if it can be determined not  to  refer
       to  an  interactive  device.  The error and end-of-file indicators for the stream shall be
       cleared.

       If mode is w, wb, a, ab, w+, wb+, w+b, a+, ab+, or a+b, and the file  did  not  previously
       exist,  upon  successful  completion,  the  fopen()  function  shall  mark  for update the
       st_atime, st_ctime, and st_mtime fields of the file and the st_ctime and  st_mtime  fields
       of the parent directory.

       If  mode  is  w,  wb,  w+, wb+, or w+b, and the file did previously exist, upon successful
       completion, fopen() shall mark for update the st_ctime and st_mtime fields  of  the  file.
       The fopen() function shall allocate a file descriptor as open() does.

       After  a  successful  call to the fopen() function, the orientation of the stream shall be
       cleared,    the encoding rule shall be cleared,  and the associated mbstate_t object shall
       be set to describe an initial conversion state.

       The  largest  value  that can be represented correctly in an object of type off_t shall be
       established as the offset maximum in the open file description.

RETURN VALUE

       Upon successful completion, fopen() shall return a pointer to the object  controlling  the
       stream. Otherwise, a null pointer shall be returned,    and errno shall be set to indicate
       the error.

ERRORS

       The fopen() function shall fail if:

       EACCES Search permission is denied on a component of the path prefix, or the  file  exists
              and  the  permissions  specified by mode are denied, or the file does not exist and
              write permission is denied for the parent directory of the file to be created.

       EINTR  A signal was caught during fopen().

       EISDIR The named file is a directory and mode requires write access.

       ELOOP  A loop exists in symbolic links encountered during resolution of the path argument.

       EMFILE {OPEN_MAX} file descriptors are currently open in the calling process.

       ENAMETOOLONG

              The length of the filename argument exceeds {PATH_MAX} or a pathname  component  is
              longer than {NAME_MAX}.

       ENFILE The maximum allowable number of files is currently open in the system.

       ENOENT A  component  of  filename  does  not name an existing file or filename is an empty
              string.

       ENOSPC The directory or file system that would contain the new file  cannot  be  expanded,
              the file does not exist, and the file was to be created.

       ENOTDIR
              A component of the path prefix is not a directory.

       ENXIO  The  named  file  is  a  character  special  or  block special file, and the device
              associated with this special file does not exist.

       EOVERFLOW
              The named file is a regular file and the size of the  file  cannot  be  represented
              correctly in an object of type off_t.

       EROFS  The named file resides on a read-only file system and mode requires write access.

       The fopen() function may fail if:

       EINVAL The value of the mode argument is not valid.

       ELOOP  More  than  {SYMLOOP_MAX}  symbolic links were encountered during resolution of the
              path argument.

       EMFILE {FOPEN_MAX} streams are currently open in the calling process.

       EMFILE {STREAM_MAX} streams are currently open in the calling process.

       ENAMETOOLONG

              Pathname resolution of a symbolic link produced an intermediate result whose length
              exceeds {PATH_MAX}.

       ENOMEM Insufficient storage space is available.

       ETXTBSY
              The  file  is  a  pure procedure (shared text) file that is being executed and mode
              requires write access.

       The following sections are informative.

EXAMPLES

   Opening a File
       The following example tries to open the file named file for reading. The fopen()  function
       returns  a  file  pointer  that  is used in subsequent fgets() and fclose() calls.  If the
       program cannot open the file, it just ignores it.

              #include <stdio.h>
              ...
              FILE *fp;
              ...
              void rgrep(const char *file)
              {
              ...
                  if ((fp = fopen(file, "r")) == NULL)
                      return;
              ...
              }

APPLICATION USAGE

       None.

RATIONALE

       None.

FUTURE DIRECTIONS

       None.

SEE ALSO

       fclose() , fdopen() , freopen() , the Base  Definitions  volume  of  IEEE Std 1003.1-2001,
       <stdio.h>

COPYRIGHT

       Portions  of  this  text  are  reprinted  and  reproduced in electronic form from IEEE Std
       1003.1, 2003 Edition, Standard for Information Technology  --  Portable  Operating  System
       Interface  (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003 by
       the Institute of Electrical and Electronics Engineers, Inc and  The  Open  Group.  In  the
       event  of  any  discrepancy  between this version and the original IEEE and The Open Group
       Standard, the original IEEE and The Open Group  Standard  is  the  referee  document.  The
       original Standard can be obtained online at http://www.opengroup.org/unix/online.html .