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