newlib/libc/stdio/fopen.c

   1 /*
   2  * Copyright (c) 1990 The Regents of the University of California.
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms are permitted
   6  * provided that the above copyright notice and this paragraph are
   7  * duplicated in all such forms and that any documentation,
   8  * advertising materials, and other materials related to such
   9  * distribution and use acknowledge that the software was developed
  10  * by the University of California, Berkeley.  The name of the
  11  * University may not be used to endorse or promote products derived
  12  * from this software without specific prior written permission.
  13  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
  14  * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
  15  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  16  */
  17
  18 /*
  19 FUNCTION
  20 <<fopen>>---open a file
  21
  22 INDEX
  23         fopen
  24 INDEX
  25         _fopen_r
  26
  27 ANSI_SYNOPSIS
  28         #include <stdio.h>
  29         FILE *fopen(const char *<[file]>, const char *<[mode]>);
  30
  31         FILE *_fopen_r(void *<[reent]>,
  32                        const char *<[file]>, const char *<[mode]>);
  33
  34 TRAD_SYNOPSIS
  35         #include <stdio.h>
  36         FILE *fopen(<[file]>, <[mode]>)
  37         char *<[file]>;
  38         char *<[mode]>;
  39
  40         FILE *_fopen_r(<[reent]>, <[file]>, <[mode]>)
  41         char *<[reent]>;
  42         char *<[file]>;
  43         char *<[mode]>;
  44
  45 DESCRIPTION
  46 <<fopen>> initializes the data structures needed to read or write a
  47 file.  Specify the file's name as the string at <[file]>, and the kind
  48 of access you need to the file with the string at <[mode]>.
  49
  50 The alternate function <<_fopen_r>> is a reentrant version.
  51 The extra argument <[reent]> is a pointer to a reentrancy structure.
  52
  53 Three fundamental kinds of access are available: read, write, and append.
  54 <<*<[mode]>>> must begin with one of the three characters `<<r>>',
  55 `<<w>>', or `<<a>>', to select one of these:
  56
  57 o+
  58 o r
  59 Open the file for reading; the operation will fail if the file does
  60 not exist, or if the host system does not permit you to read it.
  61
  62 o w
  63 Open the file for writing @emph{from the beginning} of the file:
  64 effectively, this always creates a new file.  If the file whose name you
  65 specified already existed, its old contents are discarded.
  66
  67 o a
  68 Open the file for appending data, that is writing from the end of
  69 file.  When you open a file this way, all data always goes to the
  70 current end of file; you cannot change this using <<fseek>>.
  71 o-
  72
  73 Some host systems distinguish between ``binary'' and ``text'' files.
  74 Such systems may perform data transformations on data written to, or
  75 read from, files opened as ``text''.
  76 If your system is one of these, then you can append a `<<b>>' to any
  77 of the three modes above, to specify that you are opening the file as
  78 a binary file (the default is to open the file as a text file).
  79
  80 `<<rb>>', then, means ``read binary''; `<<wb>>', ``write binary''; and
  81 `<<ab>>', ``append binary''.
  82
  83 To make C programs more portable, the `<<b>>' is accepted on all
  84 systems, whether or not it makes a difference.
  85
  86 Finally, you might need to both read and write from the same file.
  87 You can also append a `<<+>>' to any of the three modes, to permit
  88 this.  (If you want to append both `<<b>>' and `<<+>>', you can do it
  89 in either order: for example, <<"rb+">> means the same thing as
  90 <<"r+b">> when used as a mode string.)
  91
  92 Use <<"r+">> (or <<"rb+">>) to permit reading and writing anywhere in
  93 an existing file, without discarding any data; <<"w+">> (or <<"wb+">>)
  94 to create a new file (or begin by discarding all data from an old one)
  95 that permits reading and writing anywhere in it; and <<"a+">> (or
  96 <<"ab+">>) to permit reading anywhere in an existing file, but writing
  97 only at the end.
  98
  99 RETURNS
 100 <<fopen>> returns a file pointer which you can use for other file
 101 operations, unless the file you requested could not be opened; in that
 102 situation, the result is <<NULL>>.  If the reason for failure was an
 103 invalid string at <[mode]>, <<errno>> is set to <<EINVAL>>.
 104
 105 PORTABILITY
 106 <<fopen>> is required by ANSI C.
 107
 108 Supporting OS subroutines required: <<close>>, <<fstat>>, <<isatty>>,
 109 <<lseek>>, <<open>>, <<read>>, <<sbrk>>, <<write>>.
 110 */
 111
 112 #if defined(LIBC_SCCS) && !defined(lint)
 113 static char sccsid[] = "%W% (Berkeley) %G%";
 114 #endif /* LIBC_SCCS and not lint */
 115
 116 #include <stdio.h>
 117 #include <errno.h>
 118 #include "local.h"
 119
 120 FILE *
 121 _DEFUN (_fopen_r, (ptr, file, mode),
 122         struct _reent *ptr _AND
 123         _CONST char *file _AND
 124         _CONST char *mode)
 125 {
 126   register FILE *fp;
 127   register int f;
 128   int flags, oflags;
 129
 130   if ((flags = __sflags (ptr, mode, &oflags)) == 0)
 131     return NULL;
 132   if ((fp = __sfp (ptr)) == NULL)
 133     return NULL;
 134
 135   if ((f = _open_r (fp->_data, file, oflags, 0666)) < 0)
 136     {
 137       fp->_flags = 0;           /* release */
 138       return NULL;
 139     }
 140
 141   fp->_file = f;
 142   fp->_flags = flags;
 143   fp->_cookie = (_PTR) fp;
 144   fp->_read = __sread;
 145   fp->_write = __swrite;
 146   fp->_seek = __sseek;
 147   fp->_close = __sclose;
 148
 149   if (fp->_flags & __SAPP)
 150     fseek (fp, 0, SEEK_END);
 151
 152   return fp;
 153 }
 154
 155 #ifndef _REENT_ONLY
 156
 157 FILE *
 158 _DEFUN (fopen, (file, mode),
 159         _CONST char *file _AND
 160         _CONST char *mode)
 161 {
 162   return _fopen_r (_REENT, file, mode);
 163 }
 164
 165 #endif