@node _dos_creatnew, dos
@findex _dos_creatnew
@subheading Syntax

@example
#include <dos.h>

unsigned int _dos_creatnew(const char *filename, unsigned short attr,
                           int *handle);
@end example

@subheading Description

This is a direct connection to the MS-DOS create unique function call
(%ah = 0x5B).  This function creates the given file with the given
attribute and puts file handle into @var{handle} if creating is successful.
This function will fail if the specified file exists.  Meaning of
@var{attr} parameter is the following:

@table @code

@item _A_NORMAL (0x00)

Normal file (no read/write restrictions)

@item _A_RDONLY (0x01)

Read only file

@item _A_HIDDEN (0x02)

Hidden file

@item _A_SYSTEM (0x04)

System file

@item _A_ARCH (0x20)

Archive file

@end table

See also @ref{_dos_open}, @ref{_dos_creat}, @ref{_dos_read},
@ref{_dos_write}, and @ref{_dos_close}.

This function does not support long filenames, even on systems where the
LFN API (@pxref{_use_lfn, LFN}) is available.  For LFN-aware functions
with similar functionality see @ref{_creatnew}, and @ref{_creat}.  Also
see @ref{creat}, and @ref{open}, which are Posix-standard.

@subheading Return Value

Returns 0 if successful or DOS error code on error (and sets @code{errno}).

@subheading Portability

@portability !ansi, !posix

@subheading Example

@example
int handle;

if ( !_dos_creatnew("FOO.DAT", _A_NORMAL, &handle) )
   puts("Creating was successful !");
@end example