This documentation is archived and is not being maintained.

_creat, _wcreat

Creates a new file.

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


Name of new file.
Permission setting.

Return Value

These functions, if successful, return a file descriptor to the created file. Otherwise, the function returns –1 and sets errno as follows:

errno setting 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 could not be found.

See _doserrno, errno, _sys_errlist, and _sys_nerr for more information on these and other return codes.


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.

Generic-Text Routine Mappings

TCHAR.H routine _UNICODE & _MBCS not defined _MBCS defined _UNICODE defined
_tcreat _creat _creat _wcreat

If the file specified by filename does not 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 is 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 are joined with the bitwise OR operator ( | ). The pmode parameter is set to one of the following values:

Writing permitted.
Reading permitted.
Reading and writing permitted.

If write permission is not given, the file is read-only. All files are always readable; it is 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.


Routine Required header Optional headers Compatibility
_creat <io.h> <sys/types.h>, <sys/stat.h>, <errno.h> Win 98, Win Me, Win NT, Win 2000, Win XP
_wcreat <io.h> or <wchar.h> <sys/types.h>, <sys/stat.h>, <errno.h> Win NT, Win 2000, Win XP

For additional compatibility information, see Compatibility in the Introduction.


All versions of the C run-time libraries.


// crt_creat.c
/* 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 );
   if( fh == -1 )
      perror( "Couldn't create data file" );
      printf( "Created data file.\n" );
      _close( fh );


Created data file.

See Also

Low-Level I/O Routines | _chmod | _chsize | _close | _dup | _open | _sopen | _umask | Run-Time Routines and .NET Framework Equivalents