2 * Copyright (c) 1990 The Regents of the University of California.
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.
20 <<fopen>>---open a file
29 FILE *fopen(const char *<[file]>, const char *<[mode]>);
31 FILE *_fopen_r(void *<[reent]>,
32 const char *<[file]>, const char *<[mode]>);
36 FILE *fopen(<[file]>, <[mode]>)
40 FILE *_fopen_r(<[reent]>, <[file]>, <[mode]>)
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]>.
50 The alternate function <<_fopen_r>> is a reentrant version.
51 The extra argument <[reent]> is a pointer to a reentrancy structure.
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:
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.
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.
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>>.
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).
80 `<<rb>>', then, means ``read binary''; `<<wb>>', ``write binary''; and
81 `<<ab>>', ``append binary''.
83 To make C programs more portable, the `<<b>>' is accepted on all
84 systems, whether or not it makes a difference.
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.)
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
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>>.
106 <<fopen>> is required by ANSI C.
108 Supporting OS subroutines required: <<close>>, <<fstat>>, <<isatty>>,
109 <<lseek>>, <<open>>, <<read>>, <<sbrk>>, <<write>>.
112 #if defined(LIBC_SCCS) && !defined(lint)
113 static char sccsid[] = "%W% (Berkeley) %G%";
114 #endif /* LIBC_SCCS and not lint */
124 _DEFUN (_fopen_r, (ptr, file, mode),
125 struct _reent *ptr _AND
126 _CONST char *file _AND
133 if ((flags = __sflags (ptr, mode, &oflags)) == 0)
135 if ((fp = __sfp (ptr)) == NULL)
138 if ((f = _open_r (fp->_data, file, oflags, 0666)) < 0)
140 fp->_flags = 0; /* release */
146 fp->_cookie = (_PTR) fp;
148 fp->_write = __swrite;
150 fp->_close = __sclose;
152 if (fp->_flags & __SAPP)
153 fseek (fp, 0, SEEK_END);
156 if (setmode(fp->_file, O_BINARY) == O_TEXT)
157 fp->_flags |= __SCLE;
166 _DEFUN (fopen, (file, mode),
167 _CONST char *file _AND
170 return _fopen_r (_REENT, file, mode);