# fopen

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           fopen — open a stream
    


## SYNOPSIS



           #include <stdio.h>
    
           FILE *fopen(const char *restrict _pathname_ , const char *restrict _mode_);
    


## DESCRIPTION



           The functionality described on this reference page is aligned with
           the ISO C standard. Any conflict between the requirements
           described here and the ISO C standard is unintentional. This
           volume of POSIX.1‐2017 defers to the ISO C standard.
    
           The _fopen_() function shall open the file whose pathname is the
           string pointed to by _pathname_ , 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, _fopen_()
           shall mark for update the last data access, last data
           modification, and last file status change timestamps of the file
           and the last file status change and last data modification
           timestamps of the parent directory.
    
           If _mode_ is _w_ , _wb_ , _a_ , _ab_ , _w_ +, _wb_ +, _w_ +_b_ , _a_ +, _ab_ +, or _a_ +_b_ , and the
           file did not previously exist, the _fopen_() function shall create a
           file as if it called the _creat_() function with a value appropriate
           for the _path_ argument interpreted from _pathname_ and a value of
           S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH | S_IWOTH for the
           _mode_ argument.
    
           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 last data modification and last file status change timestamps
           of the file.
    
           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 file descriptor associated with the opened stream shall be
           allocated and opened as if by a call to _open_() with the following
           flags:
                   ┌──────────────────┬───────────────────────────┐
                   │   _fopen_**() Mode** │       _open_**() Flags** │
                   ├──────────────────┼───────────────────────────┤
                   │ _r_ or _rb_          │ O_RDONLY                  │
                   │ _w_ or _wb_          │ O_WRONLY|O_CREAT|O_TRUNC  │
                   │ _a_ or _ab_          │ O_WRONLY|O_CREAT|O_APPEND │
                   │ _r+_ or _rb+_ or _r+b_ │ O_RDWR                    │
                   │ _w+_ or _wb+_ or _w+b_ │ O_RDWR|O_CREAT|O_TRUNC    │
                   │ _a+_ or _ab+_ or _a+b_ │ O_RDWR|O_CREAT|O_APPEND   │
                   └──────────────────┴───────────────────────────┘
    


## 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** All file descriptors available to the process are currently
                  open.
    
           **EMFILE**{STREAM_MAX} streams are currently open in the calling
                  process.
    
           **ENAMETOOLONG**
                  The length of a pathname exceeds {PATH_MAX}, or pathname
                  resolution of a symbolic link produced an intermediate
                  result with a length that exceeds {PATH_MAX}.
    
           **ENFILE** The maximum allowable number of files is currently open in
                  the system.
    
           **ENOENT** The _mode_ string begins with **'r'** and a component of _pathname_
                  does not name an existing file, or _mode_ begins with **'w'** or
                  **'a'** and a component of the path prefix of _pathname_ does not
                  name an existing file, or _pathname_ is an empty string.
    
           **ENOENT** or **ENOTDIR**
                  The _pathname_ argument contains at least one non-<slash>
                  character and ends with one or more trailing <slash>
                  characters. If _pathname_ without the trailing <slash>
                  characters would name an existing file, an **[ENOENT]** error
                  shall not occur.
    
           **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 names an existing file that
                  is neither a directory nor a symbolic link to a directory,
                  or the _pathname_ argument contains at least one non-<slash>
                  character and ends with one or more trailing <slash>
                  characters and the last pathname component names an
                  existing file that is neither a directory nor a symbolic
                  link to 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.
    
           **ENAMETOOLONG**
                  The length of a component of a pathname is longer than
                  {NAME_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.
    


* * *