|
466
|
1 <refentry id="fopen">
|
|
|
2 <refnamediv>
|
|
|
3 <refname>fopen</refname>
|
|
570
|
4 <refpurpose>open a file and return a file pointer</refpurpose>
|
|
466
|
5 </refnamediv>
|
|
|
6
|
|
|
7 <refsynopsisdiv>
|
|
|
8 <funcsynopsis>
|
|
468
|
9 <funcsynopsisinfo>
|
|
|
10 #include <stdio.h>
|
|
|
11 </funcsynopsisinfo>
|
|
466
|
12 <funcprototype>
|
|
552
|
13 <funcdef>FILE *<function>fopen</function></funcdef>
|
|
|
14 <paramdef>char *<parameter>filename</parameter></paramdef>
|
|
|
15 <paramdef>char *<parameter>action</parameter></paramdef>
|
|
|
16 </funcprototype>
|
|
|
17
|
|
|
18 <funcprototype>
|
|
|
19 <funcdef>FILE *<function>freopen</function></funcdef>
|
|
|
20 <paramdef>char *<parameter>filename</parameter></paramdef>
|
|
|
21 <paramdef>char *<parameter>action</parameter></paramdef>
|
|
|
22 <paramdef>FILE *<parameter>streak</parameter></paramdef>
|
|
|
23 </funcprototype>
|
|
|
24
|
|
|
25 <funcprototype>
|
|
|
26 <funcdef>FILE *<function>fdopen</function></funcdef>
|
|
|
27 <paramdef>FILE *<parameter>filedes</parameter></paramdef>
|
|
|
28 <paramdef>char *<parameter>action</parameter></paramdef>
|
|
466
|
29 </funcprototype>
|
|
|
30 </funcsynopsis>
|
|
|
31
|
|
|
32 </refsynopsisdiv>
|
|
|
33
|
|
|
34 <refsect1><title>Description</title>
|
|
|
35 <para>
|
|
552
|
36 Fopen returns a pointer to a file structure (file pointer) if
|
|
|
37 the file name in the string pointed to by "filename" can be
|
|
|
38 validly opened with the action in the string pointed to by
|
|
|
39 "action".
|
|
|
40 </para>
|
|
|
41 <para>
|
|
|
42 The valid actions are:
|
|
|
43 <informaltable frame="none">
|
|
|
44 <tgroup cols="2">
|
|
|
45 <colspec colwidth="1in">
|
|
|
46 <tbody>
|
|
|
47 <row>
|
|
|
48 <entry><quote>r</quote></entry>
|
|
|
49 <entry>open for reading</entry>
|
|
|
50 </row>
|
|
|
51 <row>
|
|
|
52 <entry><quote>w</quote></entry>
|
|
|
53 <entry>create for writing</entry>
|
|
|
54 </row>
|
|
|
55 <row>
|
|
|
56 <entry><quote>a</quote></entry>
|
|
|
57 <entry>append(write) at end of file, or create for writing</entry>
|
|
|
58 </row>
|
|
|
59 <row>
|
|
|
60 <entry><quote>r+</quote></entry>
|
|
|
61 <entry>open for update</entry>
|
|
|
62 </row>
|
|
|
63 <row>
|
|
|
64 <entry><quote>w+</quote></entry>
|
|
|
65 <entry>create for update</entry>
|
|
|
66 </row>
|
|
|
67 <row>
|
|
|
68 <entry><quote>a+</quote></entry>
|
|
|
69 <entry>create or open for update at end of file</entry>
|
|
|
70 </row>
|
|
|
71 <row>
|
|
|
72 <entry><quote>d</quote></entry>
|
|
|
73 <entry>directory read</entry>
|
|
|
74 </row>
|
|
|
75 </tbody>
|
|
|
76 </tgroup>
|
|
|
77 </informaltable>
|
|
|
78 </para>
|
|
|
79 <para>
|
|
|
80 Any action may have an <quote>x</quote> after the initial letter which
|
|
|
81 indicates to <quote>fopen()</quote> that it should look in the current
|
|
|
82 execution directory if a full path is not given, and
|
|
|
83 the x also specifies that the file should have execute permission.
|
|
|
84 <informalexample>
|
|
|
85 <para>
|
|
|
86 E.g. f = fopen(<quote>fred</quote>,<quote>wx</quote>);
|
|
|
87 </para>
|
|
|
88 </informalexample>
|
|
|
89 </para>
|
|
|
90 <para>
|
|
|
91 Opening for write will perform a <quote>creat()</quote>. If a file with the
|
|
|
92 same name exists when the file is opened for write, it will be truncated
|
|
|
93 to zero length. Append means open for write and
|
|
|
94 position to the end of the file. Writes to the file via
|
|
|
95 <quote>putc()</quote> etc. will extend the file. Only if the file does not
|
|
|
96 already exist will it be created.
|
|
|
97 </para>
|
|
|
98 <para>
|
|
|
99 NOTE that the type of a file structure is pre-defined in
|
|
|
100 <quote>stdio.h</quote> as FILE, so that a user program may decale or define
|
|
|
101 a file pointer by, for example, FILE *f;
|
|
|
102 </para>
|
|
|
103 <para>
|
|
|
104 Three file pointers are available and can be considered open
|
|
|
105 the moment the program runs:
|
|
|
106
|
|
|
107 <informaltable frame="none">
|
|
|
108 <tgroup cols="2">
|
|
|
109 <colspec colwidth="1in">
|
|
|
110 <tbody>
|
|
|
111 <row>
|
|
|
112 <entry>stdin</entry>
|
|
|
113 <entry>the standard input - equivalent to path number 0</entry>
|
|
|
114 </row>
|
|
|
115 <row>
|
|
|
116 <entry>stdout</entry>
|
|
|
117 <entry>the standard output - equivalent to path number 1</entry>
|
|
|
118 </row>
|
|
|
119 <row>
|
|
|
120 <entry>stderr</entry>
|
|
|
121 <entry>the standard error output - equivalent to path number 2</entry>
|
|
|
122 </row>
|
|
|
123 </tbody>
|
|
|
124 </tgroup>
|
|
|
125 </informaltable>
|
|
|
126 </para>
|
|
|
127 <para>
|
|
|
128 All files are automatically buffered except stderr, unless a
|
|
|
129 file is made unbuffered by a call to setbuf() (q.v.).
|
|
|
130 </para>
|
|
|
131 <para>
|
|
|
132 Freopen is usually used to attach stdin, stdout, and stderr to
|
|
|
133 specified files. Freopen substitutes the file passed to it
|
|
|
134 instead of the open stream. The original stream is closed.
|
|
|
135 NOTE that the original stream will be closed even if the open
|
|
|
136 does not succeed.
|
|
|
137 </para>
|
|
|
138 <para>
|
|
|
139 Fdopen associates a stream with a file descriptor. The streams
|
|
|
140 type(r,w,a) must be the same as the mode of the open file.
|
|
|
141 </para>
|
|
|
142 </refsect1>
|
|
|
143
|
|
|
144 <refsect1><title>Caveats</title>
|
|
|
145 <para>
|
|
|
146 The <quote>action</quote> passed as an argument to fopen must be a pointer
|
|
|
147 to a string, <emphasis>not</emphasis> a character. For example
|
|
|
148 <literallayout>
|
|
|
149 fp = fopen(<quote>fred</quote>,<quote>r</quote>); is correct but
|
|
|
150 fp = fopen(<quote>fred</quote>,'r'); is not.
|
|
|
151 </literallayout>
|
|
|
152 </para>
|
|
|
153 </refsect1>
|
|
|
154
|
|
|
155 <refsect1><title>Diagnostics</title>
|
|
|
156 <para>
|
|
|
157 Fopen returns NULL (0) if the call was unsuccessful.
|
|
466
|
158 </para>
|
|
|
159 </refsect1>
|
|
542
|
160
|
|
|
161 <refsect1><title>See Also</title>
|
|
|
162 <para>
|
|
|
163 System call
|
|
|
164 <link linkend="open">open()</link>,
|
|
570
|
165 <link linkend="fclose">fclose()</link>
|
|
542
|
166 </para>
|
|
|
167 </refsect1>
|
|
|
168
|
|
466
|
169 </refentry>
|
