_creat, _wcreat

Creates a new file. _creat and _wcreat have been deprecated; use _sopen_s, _wsopen_s instead.

Syntax

int _creat(
   const char *filename,
   int pmode
);
int _wcreat(
   const wchar_t *filename,
   int pmode
);

Parameters

filename
Name of new file.

pmode
Permission setting.

Return value

These functions, if successful, return a file descriptor to the created file. Otherwise, the functions return -1 and set errno as shown in the following table.

errno value	Description
EACCES	filename specifies an existing read-only file or specifies a directory instead of a file.
EMFILE	No more file descriptors are available.
ENOENT	Specified file couldn't be found.

If filename is NULL, these functions invoke the invalid parameter handler, as described in Parameter validation. If execution is allowed to continue, these functions set errno to EINVAL and return -1.

For more information about these and other return codes, see errno, _doserrno, _sys_errlist, and _sys_nerr.

Remarks

The _creat function creates a new file or opens and truncates an existing one. _wcreat is a wide-character version of _creat; the filename argument to _wcreat is a wide-character string. _wcreat and _creat behave identically otherwise.

By default, this function's global state is scoped to the application. To change it, see Global state in the CRT.

Generic-text routine mappings

Tchar.h routine	_UNICODE and _MBCS not defined	_MBCS defined	_UNICODE defined
_tcreat	_creat	_creat	_wcreat

If the file specified by filename doesn't exist, a new file is created with the given permission setting and is opened for writing. If the file already exists and its permission setting allows writing, _creat truncates the file to length 0, destroying the previous contents, and opens it for writing. The permission setting, pmode, applies to newly created files only. The new file receives the specified permission setting after it's closed for the first time. The integer expression pmode contains one or both of the manifest constants _S_IWRITE and _S_IREAD, defined in SYS\Stat.h. When both constants are given, they're joined with the bitwise or operator ( | ). The pmode parameter is set to one of the following values.

Value	Definition
_S_IWRITE	Writing permitted.
_S_IREAD	Reading permitted.
_S_IREAD | _S_IWRITE	Reading and writing permitted.

If write permission isn't given, the file is read-only. All files are always readable; it's impossible to give write-only permission. The modes _S_IWRITE and _S_IREAD | _S_IWRITE are then equivalent. Files opened using _creat are always opened in compatibility mode (see _sopen) with _SH_DENYNO.

_creat applies the current file-permission mask to pmode before setting the permissions (see _umask). _creat is provided primarily for compatibility with previous libraries. A call to _open with _O_CREAT and _O_TRUNC in the oflag parameter is equivalent to _creat and is preferable for new code.

Requirements

Routine	Required header	Optional header
_creat	<io.h>	<sys/types.h>, <sys/stat.h>, <errno.h>
_wcreat	<io.h> or <wchar.h>	<sys/types.h>, <sys/stat.h>, <errno.h>

For more compatibility information, see Compatibility.

Example

// crt_creat.c
// compile with: /W3
// This program uses _creat to create
// the file (or truncate the existing file)
// named data and open it for writing.

#include <sys/types.h>
#include <sys/stat.h>
#include <io.h>
#include <stdio.h>
#include <stdlib.h>

int main( void )
{
   int fh;

   fh = _creat( "data", _S_IREAD | _S_IWRITE ); // C4996
   // Note: _creat is deprecated; use _sopen_s instead
   if( fh == -1 )
      perror( "Couldn't create data file" );
   else
   {
      printf( "Created data file.\n" );
      _close( fh );
   }
}

Created data file.

See also

Low-level I/O
_chmod, _wchmod
_chsize
_close
_dup, _dup2
_open, _wopen
_sopen, _wsopen
_umask