Manual Pages for UNIX Operating System command usage for man fopen

Standard C Library Functions                            fopen(3C)



NAME
     fopen - open a stream

SYNOPSIS
     #include 

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


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


     The argument mode points to a string beginning with  one  of
     the following sequences:

     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  writ-
                         ing).


     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 has no effect, but  is  allowed  for  ISO  C
     standard conformance (see standards(5)). Opening a file with
     read mode (r as the first character in  the  mode  argument)
     fails 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) causes all subsequent writes to the file
     to be forced to the then current end-of-file, regardless  of
     intervening  calls  to  fseek(3C). If two separate processes



SunOS 5.11          Last change: 18 Apr 2006                    1






Standard C Library Functions                            fopen(3C)



     open the same file for append, each process may write freely
     to  the file without fear of destroying output being written
     by the other.  The output from the  two  processes  will  be
     intermixed in the file in the order in which it is written.


     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,  output
     must  not be directly followed by input without an interven-
     ing call to fflush(3C) or to a file positioning  function  (
     fseek(3C), fsetpos(3C) or rewind(3C)), and input must not be
     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 are cleared.


     If mode begins with w or a and the file did  not  previously
     exist,  upon  successful  completion,  fopen() function will
     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 begins with w and the  file  did  previously  exist,
     upon successful completion, fopen() will mark for update the
     st_ctime and st_mtime fields of the file.  The fopen() func-
     tion will allocate a file descriptor as open(2) does.


     Normally, 32-bit applications return an  EMFILE  error  when
     attempting  to  associate a stream with a file accessed by a
     file descriptor with a value greater than 255. If  the  last
     character  of mode is F, 32-bit applications will be allowed
     to associate a  stream  with  a  file  accessed  by  a  file
     descriptor  with  a  value  greater than 255. A FILE pointer
     obtained in this way must never be used  by  any  code  that
     might  directly  access fields in the FILE structure. If the
     fields in the FILE structure are  used  directly  by  32-bit
     applications  when  the  last  character  of mode is F, data
     corruption could occur. See the USAGE section of this manual
     page  and the enable_extended_FILE_stdio(3C) manual page for
     other options for enabling the extended FILE facility.


     In 64-bit  applications,  the  last  character  of  mode  is
     silently ignored if it is F.  64-bit applications are always



SunOS 5.11          Last change: 18 Apr 2006                    2






Standard C Library Functions                            fopen(3C)



     allowed to associate a stream with a file accessed by a file
     descriptor with any value.


     The largest value that can be represented  correctly  in  an
     object  of type off_t will be established as the offset max-
     imum in the open file description.

RETURN VALUES
     Upon successful completion, fopen() returns a pointer to the
     object controlling the stream.  Otherwise, a null pointer is
     returned and errno is set to indicate the error.


     The fopen() function may fail and not set errno if there are
     no free stdio streams.

ERRORS
     The fopen() function will 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  direc-
                     tory of the file to be created.


     EINTR           A signal was caught during the execution  of
                     fopen().


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


     ELOOP           Too many symbolic links were encountered  in
                     resolving path.


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


     ENAMETOOLONG    The length of the filename 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.




SunOS 5.11          Last change: 18 Apr 2006                    3






Standard C Library Functions                            fopen(3C)



     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 con-
                     tain  the  new  file cannot be expanded, the
                     file does  not  exist,  and  it  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 associ-
                     ated with this special file does not exist.


     EOVERFLOW       The current value of the file position  can-
                     not be represented correctly in an object of
                     type fpos_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.


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

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


     ENAMETOOLONG    Pathname resolution of a symbolic link  pro-
                     duced  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



SunOS 5.11          Last change: 18 Apr 2006                    4






Standard C Library Functions                            fopen(3C)



                     requires write access.


USAGE
     A process is allowed to  have  at  least  {FOPEN_MAX}  stdio
     streams  open  at  a time. For 32-bit applications, however,
     the underlying ABIs formerly required that no file  descrip-
     tor used to access the file underlying a stdio stream have a
     value greater than 255.  To  maintain  binary  compatibility
     with  earlier  Solaris releases, this limit still constrains
     32-bit applications. However, when a 32-bit  application  is
     aware  that  no  code  that  has  access to the FILE pointer
     returned by fopen() will use the FILE  pointer  to  directly
     access any fields in the FILE structure, the F character can
     be used as the last character in the mode argument  to  cir-
     cumvent  this  limit.  Because it could lead to data corrup-
     tion, the F character in mode must never be  used  when  the
     FILE  pointer  might later be used by binary code unknown to
     the user. The F character in mode is intended to be used  by
     library functions that need a FILE pointer to access data to
     process a user request, but do not need  to  pass  the  FILE
     pointer back to the user. 32-bit applications that have been
     inspected can use the extended FILE facility  to  circumvent
     this  limit  if  the  inspection shows that no FILE pointers
     will be used to directly access FILE structure contents.


     The fopen() function has a transitional interface for 64-bit
     file offsets.  See lf64(5).

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|
    | Standard                    | See below.                  |
    |_____________________________|_____________________________|



     For all aspects of this function except the F  character  in
     the mode argument, see standards(5)





SunOS 5.11          Last change: 18 Apr 2006                    5






Standard C Library Functions                            fopen(3C)



SEE ALSO
     enable_extended_FILE_stdio(3C),   fclose(3C),    fdopen(3C),
     fflush(3C),  freopen(3C),  fsetpos(3C),  rewind(3C),  attri-
     butes(5), lf64(5), standards(5)



















































SunOS 5.11          Last change: 18 Apr 2006                    6