<refentry id="creat">
<refnamediv>
<refname>Creat</refname>
<refpurpose>create a file</refpurpose>
</refnamediv>

<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>
#include &lt;modes.h&gt;
</funcsynopsisinfo>
<funcprototype>
  <funcdef><function>creat</function></funcdef>
  <paramdef>char *<parameter>fname</parameter></paramdef>
  <paramdef>int <parameter>perm</parameter></paramdef>
</funcprototype>
</funcsynopsis>

</refsynopsisdiv>

<refsect1><title>Assembler Equivalent</title>
<para>
os9 I$CREATE
</para>
</refsect1>

<refsect1><title>Description</title>
<para>
Creat returns a path number to a new file available for
writing, giving it the permissions specified in "perm" and
making the task user the owner. If, however, "fname" is the
name of an existing file, the file is truncated to zero length,
and the ownership and permissions remain unchanged. NOTE,
that unlike the OS-9 assembler service request, creat does
not return an error if the file already exists. "Access()"
should be used to establish the existence of a file if it is
important that a file should not be overwritten.
</para>
<para>
It is unnecessary to specify writing permissions in "perm" in
order to write to the file in the current task.
</para>
<para>
The permissions allowed are defined in the include file as
follows:
</para>
<programlisting>
#define  S_IPRM    0xff     /* mask for permission bits */
#define  S_IREAD   0x01     /* owner read */
#define  S_IWRITE  0x02     /* owner write */
#define  S_IEXEC   0x04     /* owner execute */
#define  S_IOREAD  0x08     /* public read */
#define  S_IOWRITE 0x10     /* public write */
#define  S_IOEXEC  0x20     /* public execute */
#define  S_ISHARE  0x40     /* sharable */
</programlisting>
<para>
Directories may not be created with this call; use "mknod()"
instead.
</para>
</refsect1>

<refsect1><title>Diagnostics</title>
<para>
This call returns -1 if there are too many files open. If the
pathname cannot be searched, if permission to write is denied,
or if the file exists and is a directory.
</para>
</refsect1>

<refsect1><title>See Also</title>
<para>
<link linkend="write">write()</link>,
<link linkend="close">close()</link>,
<link linkend="chmod">chmod()</link>
</para>
</refsect1>
</refentry>