_creat, _wcreat

Article
12/18/2017

The latest version of this topic can be found at _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` 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.

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 _doserrno, errno, _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.

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 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.

Value	Definition
`_S_IWRITE`	Writing permitted.
`_S_IREAD`	Reading permitted.
`_S_IREAD \| _S_IWRITE`	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.

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 in the Introduction.

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.

Share via