_creatnew

Syntax

#include <fcntl.h> #include <dir.h> #include <io.h> int _creatnew(const char *path, int attrib, int flags);

Description

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

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

FA_RDONLY (1)

The file is created with the read-only bit set.

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.

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.

Other bits (FA_LABEL and FA_DIREC) are ignored by DOS.

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

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.

SH_DENYRW (10h)

Denies both read and write access by other processes.

SH_DENYWR (20h)

Denies write access by other processes.

SH_DENYRD (30h)

Denies read access by other processes.

SH_DENYNO (40h)

Allows read and write access by other processes, but prevents other processes from opening the file in compatibility mode.

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

_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 flags, since function 6C00h is only supported by DOS 4.0 and later.)

The file handle returned by _creatnew is set to binary mode.

This function can be hooked by the Filesystem Extensions handlers, as described in File System Extensions. If you don't want this, you should use _dos_creatnew (see section _dos_creatnew) instead.

Return Value

The new file descriptor, else -1 on error.

Portability

ANSI/ISO C	No
POSIX	No