@node _creatnew, file system
@findex _creatnew
@subheading Syntax

@example
#include <fcntl.h>
#include <dir.h>
#include <io.h>

int _creatnew(const char *path, int attrib, int flags);
@end example

@subheading Description

This function creates a file given by @var{path} and opens it, like
@code{_creat} does, but only if it didn't already exist.  If the named
file exists, @code{_creatnew} fails.  (In contrast, @code{_creat} opens
existing files and overwrites their contents, see @ref{_creat}.)

The attributes of the created file are determined by @var{attrib}.  The
file is usually given the normal attribute (00H).  If @var{attrib} is
non-zero, additional attributes will be set.  The following macros,
defined on @code{<dir.h>}, can be used to control the attributes of the
created file (the associated numeric values appear in parentheses):

@table @code
@item FA_RDONLY (1)
The file is created with the read-only bit set.

@item FA_HIDDEN (2)
The file is created with the hidden bit set.  Such files will not appear
in directory listings unless you use special options to the commands
which list files.

@item FA_SYSTEM (4)
The file is created with the system bit set.  Such files will not appear
in directory listings unless you use special options to the commands
which list files.
@end table

Other bits (@code{FA_LABEL} and @code{FA_DIREC}) are ignored by DOS.

The argument @var{flags} controls the sharing mode and the fine details
of how the file is handled by the operating system.  The following
macros, defined on @code{<fcntl.h>}, can be used for this (associated
numeric values are given in parentheses):

@table @code
@item SH_COMPAT (00h)
Opens the file in compatibility mode, which allows any other process to
open the file and read from the file any number of times.

@item SH_DENYRW (10h)
Denies both read and write access by other processes.

@item SH_DENYWR (20h)
Denies write access by other processes.

@item SH_DENYRD (30h)
Denies read access by other processes.

@item SH_DENYNO (40h)
Allows read and write access by other processes, but prevents other
processes from opening the file in compatibility mode.
@end table

Note that the file is always open for both reading and writing;
@code{_creatnew} ignores any bits in the lower nibble of @var{flags}
(@code{O_RDONLY}, @code{O_WRONLY}, etc.).

@code{_creatnew} calls DOS function 716Ch when long file names are
supported, 6C00h otherwise.  (On DOS version 3.x, function 5B00h is
called which ignores the value of @var{flags}, since function 6C00h is
only supported by DOS 4.0 and later.)

The file handle returned by @code{_creatnew} is set to binary mode. 

This function can be hooked by the Filesystem Extensions handlers, as
described in @ref{File System Extensions}.  If you don't want this, you
should use @code{_dos_creatnew} (@pxref{_dos_creatnew}) instead.

@subheading Return Value

The new file descriptor, else -1 on error.

@subheading Portability

@portability !ansi, !posix