Commit | Line | Data |
---|---|---|
ae59e04c | 1 | .\" Copyright (c) 1990, 1991 The Regents of the University of California. |
411867e7 | 2 | .\" All rights reserved. |
251f9c2d | 3 | .\" |
411867e7 | 4 | .\" This code is derived from software contributed to Berkeley by |
043368e6 KB |
5 | .\" Chris Torek and the American National Standards Committee X3, |
6 | .\" on Information Processing Systems. | |
7 | .\" | |
411867e7 KB |
8 | .\" %sccs.include.redist.man% |
9 | .\" | |
043368e6 | 10 | .\" @(#)fopen.3 6.8 (Berkeley) %G% |
411867e7 | 11 | .\" |
ae59e04c CL |
12 | .Dd |
13 | .Dt FOPEN 3 | |
14 | .Os | |
15 | .Sh NAME | |
16 | .Nm fopen , | |
17 | .Nm fdopen , | |
18 | .Nm freopen | |
19 | .Nd stream open functions | |
20 | .Sh SYNOPSIS | |
21 | .Fd #include <stdio.h> | |
22 | .Ft FILE * | |
23 | .Fn fopen "char *path" "char *mode" | |
24 | .Ft FILE * | |
25 | .Fn fdopen "int fildes" "char *mode" | |
26 | .Ft FILE * | |
27 | .Fn freopen "char *path" "char *mode" "FILE *stream" | |
28 | .Sh DESCRIPTION | |
29 | The | |
30 | .Fn fopen | |
31 | function | |
32 | opens the file whose name is the string pointed to by | |
33 | .Fa path | |
34 | and associates a stream with it. | |
35 | .Pp | |
36 | The argument | |
37 | .Fa mode | |
38 | points to a string beginning with one of the following | |
39 | sequences (Additional characters may follow these sequences.): | |
40 | .Bl -tag -width indent | |
41 | .It Dq Li r | |
42 | Open text file for reading. | |
411867e7 | 43 | The stream is positioned at the beginning of the file. |
ae59e04c | 44 | .It Dq Li r+ |
411867e7 KB |
45 | Open for reading and writing. |
46 | The stream is positioned at the beginning of the file. | |
ae59e04c CL |
47 | .It Dq Li w |
48 | Truncate file to zero length or create text file for writing. | |
411867e7 | 49 | The stream is positioned at the beginning of the file. |
ae59e04c | 50 | .No It Dq Li w+ |
411867e7 KB |
51 | Open for reading and writing. |
52 | The file is created if it does not exist, otherwise it is truncated. | |
53 | The stream is positioned at the beginning of the file. | |
ae59e04c | 54 | .It Dq Li a |
411867e7 KB |
55 | Open for writing. |
56 | The file is created if it does not exist. | |
57 | The stream is positioned at the end of the file. | |
ae59e04c | 58 | .It Dq Li a+ |
411867e7 KB |
59 | Open for reading and writing. |
60 | The file is created if it does not exist. | |
61 | The stream is positioned at the end of the file. | |
ae59e04c CL |
62 | .El |
63 | .Pp | |
411867e7 | 64 | The |
ae59e04c | 65 | .Fa mode |
411867e7 KB |
66 | string can also include the letter ``b'' either as a third character or |
67 | as a character between the characters in any of the two-character strings | |
68 | described above. | |
ae59e04c CL |
69 | This is strictly for compatibility with |
70 | .St -ansiC | |
411867e7 | 71 | and has no effect; the ``b'' is ignored. |
ae59e04c CL |
72 | .Pp |
73 | Any created files will have mode | |
74 | .Pf \\*q Dv S_IRUSR | |
75 | \&| | |
76 | .Dv S_IWUSR | |
77 | \&| | |
78 | .Dv S_IRGRP | |
79 | \&| | |
80 | .Dv S_IWGRP | |
81 | \&| | |
82 | .Dv S_IROTH | |
83 | \&| | |
84 | .Dv S_IWOTH Ns \\*q | |
85 | .Pq Li 0666 , | |
86 | as modified by the process' | |
a4b80657 | 87 | umask value (see |
ae59e04c CL |
88 | .Xr umask 2 ) . |
89 | .Pp | |
411867e7 | 90 | Reads and writes may be intermixed on read/write streams in any order, |
ae59e04c CL |
91 | and do not require an intermediate seek as in previous versions of |
92 | .Em stdio . | |
93 | This is not portable to other systems, however; | |
94 | .Tn ANSI C | |
95 | requires that | |
411867e7 KB |
96 | a file positioning function intervene between output and input, unless |
97 | an input operation encounters end-of-file. | |
ae59e04c | 98 | .Pp |
251f9c2d | 99 | The |
ae59e04c CL |
100 | .Fn fdopen |
101 | function associates a stream with the existing file descriptor, | |
102 | .Fa fildes . | |
103 | The | |
104 | .Fa mode | |
411867e7 | 105 | of the stream must be compatible with the mode of the file descriptor. |
ae59e04c CL |
106 | .Pp |
107 | The | |
108 | .Fn freopen | |
109 | function | |
110 | opens the file whose name is the string pointed to by | |
111 | .Fa path | |
112 | and associates the stream pointed to by | |
113 | .Fa stream | |
114 | with it. | |
115 | The original stream (if it exists) is closed. | |
116 | The | |
117 | .Fa mode | |
118 | argument is used just as in the | |
119 | .Xr fopen | |
120 | function. | |
121 | The primary use of the | |
122 | .Fn freopen | |
123 | function | |
124 | is to change the file associated with a | |
125 | standard text stream | |
126 | .Pf ( Em stderr , | |
127 | .Em stdin , | |
128 | or | |
129 | .Em stdout ) . | |
130 | .Sh RETURN VALUES | |
131 | Upon successful completion | |
132 | .Fn fopen , | |
133 | .Fn fdopen | |
411867e7 | 134 | and |
ae59e04c CL |
135 | .Fn freopen |
136 | return a | |
137 | .Tn FILE | |
138 | pointer. | |
139 | Otherwise, | |
140 | .Dv NULL | |
141 | is returned and the global variable | |
142 | .Va errno | |
411867e7 | 143 | is set to indicate the error. |
ae59e04c CL |
144 | .Sh ERRORS |
145 | .Bl -tag -width [EINVAL] | |
146 | .It Bq Er EINVAL | |
147 | The | |
148 | .Fa mode | |
149 | provided to | |
150 | .Fn fopen , | |
151 | .Fn fdopen , | |
411867e7 | 152 | or |
ae59e04c | 153 | .Fn freopen |
411867e7 | 154 | was invalid. |
ae59e04c CL |
155 | .El |
156 | .Pp | |
157 | The | |
158 | .Fn fopen , | |
159 | .Fn fdopen | |
a4b80657 | 160 | and |
ae59e04c CL |
161 | .Fn freopen |
162 | functions | |
a4b80657 | 163 | may also fail and set |
ae59e04c | 164 | .Va errno |
a4b80657 | 165 | for any of the errors specified for the routine |
ae59e04c CL |
166 | .Xr malloc 3 . |
167 | .Pp | |
168 | The | |
169 | .Fn fopen | |
170 | function | |
411867e7 | 171 | may also fail and set |
ae59e04c | 172 | .Va errno |
411867e7 | 173 | for any of the errors specified for the routine |
ae59e04c CL |
174 | .Xr open 2 . |
175 | .Pp | |
176 | The | |
177 | .Fn fdopen | |
178 | function | |
411867e7 | 179 | may also fail and set |
ae59e04c | 180 | .Va errno |
411867e7 | 181 | for any of the errors specified for the routine |
ae59e04c CL |
182 | .Xr fcntl 2 . |
183 | .Pp | |
184 | The | |
185 | .Fn freopen | |
186 | function | |
411867e7 | 187 | may also fail and set |
ae59e04c | 188 | .Va errno |
411867e7 | 189 | for any of the errors specified for the routines |
ae59e04c CL |
190 | .Xr open 2 , |
191 | .Xr fclose 3 | |
411867e7 | 192 | and |
ae59e04c CL |
193 | .Xr fflush 3 . |
194 | .Sh SEE ALSO | |
195 | .Xr open 2 , | |
196 | .Xr fclose 3 , | |
197 | .Xr fseek 3 , | |
198 | .Xr funopen 3 | |
199 | .Sh STANDARDS | |
200 | The | |
201 | .Fn fopen | |
411867e7 | 202 | and |
ae59e04c CL |
203 | .Fn freopen |
204 | functions | |
205 | conform to | |
206 | .St -ansiC . | |
207 | The | |
208 | .Fn fdopen | |
209 | function | |
210 | conforms to | |
211 | .St -p1003.1-88 . |