<refentry id="fopen">
<refnamediv>
<refname>Fopen</refname>
<refpurpose>open a file and return a file pointer</refpurpose>
</refnamediv>

<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;stdio.h&gt;
</funcsynopsisinfo>
<funcprototype>
  <funcdef>FILE *<function>fopen</function></funcdef>
  <paramdef>char *<parameter>filename</parameter></paramdef>
  <paramdef>char *<parameter>action</parameter></paramdef>
</funcprototype>

<funcprototype>
  <funcdef>FILE *<function>freopen</function></funcdef>
  <paramdef>char *<parameter>filename</parameter></paramdef>
  <paramdef>char *<parameter>action</parameter></paramdef>
  <paramdef>FILE *<parameter>streak</parameter></paramdef>
</funcprototype>

<funcprototype>
  <funcdef>FILE *<function>fdopen</function></funcdef>
  <paramdef>FILE *<parameter>filedes</parameter></paramdef>
  <paramdef>char *<parameter>action</parameter></paramdef>
</funcprototype>
</funcsynopsis>

</refsynopsisdiv>

<refsect1><title>Description</title>
<para>
Fopen returns a pointer to a file structure (file pointer) if
the file name in the string pointed to by "filename" can be
validly opened with the action in the string pointed to by
"action".
</para>
<para>
The valid actions are:
<informaltable frame="none">
<tgroup cols="2">
<colspec colwidth="0.5in"/>
<colspec colwidth="3.0in"/>
<tbody>
<row>
<entry><quote>r</quote></entry>
<entry>open for reading</entry>
</row>
<row>
<entry><quote>w</quote></entry>
<entry>create for writing</entry>
</row>
<row>
<entry><quote>a</quote></entry>
<entry>append(write) at end of file, or create for writing</entry>
</row>
<row>
<entry><quote>r+</quote></entry>
<entry>open for update</entry>
</row>
<row>
<entry><quote>w+</quote></entry>
<entry>create for update</entry>
</row>
<row>
<entry><quote>a+</quote></entry>
<entry>create or open for update at end of file</entry>
</row>
<row>
<entry><quote>d</quote></entry>
<entry>directory read</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<para>
Any action may have an <quote>x</quote> after the initial letter which
indicates to <quote>fopen()</quote> that it should look in the current
execution directory if a full path is not given, and
the x also specifies that the file should have execute permission.
<informalexample>
<para>
E.g. f = fopen(<quote>fred</quote>,<quote>wx</quote>);
</para>
</informalexample>
</para>
<para>
Opening for write will perform a <quote>creat()</quote>. If a file with the
same name exists when the file is opened for write, it will be truncated
to zero length. Append means open for write and
position to the end of the file. Writes to the file via
<quote>putc()</quote> etc. will extend the file. Only if the file does not
already exist will it be created.
</para>
<para>
NOTE that the type of a file structure is pre-defined in
<quote>stdio.h</quote> as FILE, so that a user program may decale or define
a file pointer by, for example, FILE *f;
</para>
<para>
Three file pointers are available and can be considered open
the moment the program runs:

<informaltable frame="none">
<tgroup cols="2">
<colspec colwidth="0.6in"/>
<colspec colwidth="3.4in"/>
<tbody>
<row>
<entry>stdin</entry>
<entry>the standard input - equivalent to path number 0</entry>
</row>
<row>
<entry>stdout</entry>
<entry>the standard output - equivalent to path number 1</entry>
</row>
<row>
<entry>stderr</entry>
<entry>the standard error output - equivalent to path number 2</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<para>
All files are automatically buffered except stderr, unless a
file is made unbuffered by a call to setbuf() (q.v.).
</para>
<para>
Freopen is usually used to attach stdin, stdout, and stderr to
specified files. Freopen substitutes the file passed to it
instead of the open stream. The original stream is closed.
NOTE that the original stream will be closed even if the open
does not succeed.
</para>
<para>
Fdopen associates a stream with a file descriptor. The streams
type(r,w,a) must be the same as the mode of the open file.
</para>
</refsect1>

<refsect1><title>Caveats</title>
<para>
The <quote>action</quote> passed as an argument to fopen must be a pointer
to a string, <emphasis>not</emphasis> a character. For example
<literallayout>
fp = fopen(<quote>fred</quote>,<quote>r</quote>); is correct but
fp = fopen(<quote>fred</quote>,'r'); is not.
</literallayout>
</para>
</refsect1>

<refsect1><title>Diagnostics</title>
<para>
Fopen returns NULL (0) if the call was unsuccessful.
</para>
</refsect1>

<refsect1><title>See Also</title>
<para>
System call
<link linkend="open">open()</link>,
<link linkend="fclose">fclose()</link>
</para>
</refsect1>

</refentry>