Commit | Line | Data |
---|---|---|
411867e7 KB |
1 | .\" Copyright (c) 1990 The Regents of the University of California. |
2 | .\" All rights reserved. | |
251f9c2d | 3 | .\" |
411867e7 KB |
4 | .\" This code is derived from software contributed to Berkeley by |
5 | .\" Chris Torek. | |
251f9c2d | 6 | .\" |
411867e7 KB |
7 | .\" %sccs.include.redist.man% |
8 | .\" | |
a4b80657 | 9 | .\" @(#)fopen.3 6.6 (Berkeley) %G% |
411867e7 KB |
10 | .\" |
11 | .TH FOPEN 3 "" | |
12 | .UC 7 | |
251f9c2d | 13 | .SH NAME |
411867e7 | 14 | fopen, fdopen, freopen \- open a stream |
251f9c2d | 15 | .SH SYNOPSIS |
411867e7 KB |
16 | .nf |
17 | .ft B | |
18 | #include <stdio.h> | |
19 | ||
20 | FILE * | |
21 | fopen(char *path, char *type); | |
22 | ||
23 | FILE * | |
24 | fdopen(int fildes, char *type); | |
25 | ||
26 | FILE * | |
27 | freopen(char *path, char *type, FILE *stream); | |
28 | .ft R | |
29 | .fi | |
251f9c2d KM |
30 | .SH DESCRIPTION |
31 | .I Fopen | |
32 | opens the file named by | |
411867e7 KB |
33 | .I path |
34 | and associates a stream with it, returning a pointer for identifying | |
35 | the stream in subsequent operations. | |
251f9c2d KM |
36 | .PP |
37 | .I Type | |
411867e7 KB |
38 | is one of the following character strings: |
39 | .TP | |
40 | ``r'' | |
41 | Open for reading. | |
42 | The stream is positioned at the beginning of the file. | |
43 | .TP | |
44 | ``r+'' | |
45 | Open for reading and writing. | |
46 | The stream is positioned at the beginning of the file. | |
47 | .TP | |
48 | ``w'' | |
49 | Open for writing. | |
50 | The file is created if it does not exist, otherwise it is truncated. | |
51 | The stream is positioned at the beginning of the file. | |
52 | .TP | |
53 | ``w+'' | |
54 | Open for reading and writing. | |
55 | The file is created if it does not exist, otherwise it is truncated. | |
56 | The stream is positioned at the beginning of the file. | |
57 | .TP | |
58 | ``a'' | |
59 | Open for writing. | |
60 | The file is created if it does not exist. | |
61 | The stream is positioned at the end of the file. | |
62 | .TP | |
63 | ``a+'' | |
64 | Open for reading and writing. | |
65 | The file is created if it does not exist. | |
66 | The stream is positioned at the end of the file. | |
251f9c2d | 67 | .PP |
411867e7 | 68 | The |
251f9c2d | 69 | .I type |
411867e7 KB |
70 | string can also include the letter ``b'' either as a third character or |
71 | as a character between the characters in any of the two-character strings | |
72 | described above. | |
73 | This is strictly for compatibility with ANSI X3.159-1989 (``ANSI C'') | |
74 | and has no effect; the ``b'' is ignored. | |
251f9c2d | 75 | .PP |
a4b80657 KB |
76 | Any created files will have mode ``S_IRUSR | S_IWUSR | S_IRGRP | |
77 | S_IWGRP | S_IROTH | S_IWOTH'' (0666), as modified by the process' | |
78 | umask value (see | |
411867e7 | 79 | .IR umask (2)). |
251f9c2d | 80 | .PP |
411867e7 KB |
81 | Reads and writes may be intermixed on read/write streams in any order, |
82 | and do not require an intermediate seek as in previous versions of | |
83 | stdio. | |
84 | This is not portable to other systems, however; ANSI C requires that | |
85 | a file positioning function intervene between output and input, unless | |
86 | an input operation encounters end-of-file. | |
251f9c2d KM |
87 | .PP |
88 | .I Fdopen | |
89 | associates a stream with a file descriptor obtained from | |
411867e7 KB |
90 | .IR creat (2), |
91 | .IR dup (2), | |
92 | .IR open (2), | |
251f9c2d KM |
93 | or |
94 | .IR pipe (2). | |
95 | The | |
96 | .I type | |
411867e7 KB |
97 | of the stream must be compatible with the mode of the file descriptor. |
98 | .PP | |
99 | .I Freopen | |
100 | substitutes the named file in place of the open | |
101 | .IR stream | |
102 | and returns a pointer to it. | |
103 | The original stream is closed. | |
104 | .I Freopen | |
105 | is typically used to attach the preopened constant names, | |
106 | .IR stdin , | |
107 | .IR stdout , | |
108 | and | |
109 | .I stderr | |
110 | to files. | |
251f9c2d | 111 | .SH "SEE ALSO" |
a4b80657 | 112 | open(2), fclose(3), fseek(3), funopen(3) |
411867e7 KB |
113 | .SH "RETURN VALUES" |
114 | Upon successful completion | |
115 | .IR fopen , | |
116 | .I fdopen | |
117 | and | |
118 | .I freopen | |
119 | return a FILE pointer. | |
120 | Otherwise, NULL is returned and the global variable | |
121 | .I errno | |
122 | is set to indicate the error. | |
123 | .SH ERRORS | |
124 | .TP 15 | |
125 | [EINVAL] | |
126 | The | |
127 | .I type | |
128 | provided to | |
129 | .IR fopen , | |
130 | .IR fdopen , | |
131 | or | |
132 | .IR freopen | |
133 | was invalid. | |
a4b80657 KB |
134 | .PP |
135 | .IR Fopen , | |
136 | .I fdopen | |
137 | and | |
138 | .I freopen | |
139 | may also fail and set | |
140 | .IR errno | |
141 | for any of the errors specified for the routine | |
142 | .IR malloc (3). | |
411867e7 | 143 | .PP |
251f9c2d | 144 | .I Fopen |
411867e7 KB |
145 | may also fail and set |
146 | .IR errno | |
147 | for any of the errors specified for the routine | |
148 | .IR open (2). | |
149 | .PP | |
150 | .I Fdopen | |
151 | may also fail and set | |
152 | .IR errno | |
153 | for any of the errors specified for the routine | |
154 | .IR fcntl (2). | |
155 | .PP | |
156 | .I Freopen | |
157 | may also fail and set | |
158 | .IR errno | |
159 | for any of the errors specified for the routines | |
160 | .IR open (2), | |
161 | .IR fclose (3) | |
162 | and | |
163 | .IR fflush (3). | |
164 | .SH STANDARDS | |
165 | .I Fopen | |
166 | and | |
251f9c2d | 167 | .I freopen |
411867e7 KB |
168 | conform to ANSI X3.159-1989 (``ANSI C''). |
169 | .I Fdopen | |
170 | conforms to IEEE Std 1003.1-1988 (``POSIX''). | |
251f9c2d KM |
171 | .SH BUGS |
172 | .I Fdopen | |
411867e7 | 173 | may not be portable to systems other than UNIX. |