_creat, _wcreat

Creates a new file.

int_creat(constchar*filename,intpmode**);**

int_wcreat(constwchar_t*filename,intpmode**);**

Routine	Required Header	Optional Headers	Compatibility
_creat	<io.h>	<sys/types.h>, <sys/stat.h>, <errno.h>	Win 95, Win NT
_wcreat	<io.h> or <wchar.h>	<sys/types.h>, <sys/stat.h>, <errno.h>	Win NT

For additional compatibility information, see Compatibility in the Introduction.

Libraries

LIBC.LIB	Single thread static library, retail version
LIBCMT.LIB	Multithread static library, retail version
MSVCRT.LIB	Import library for MSVCRT.DLL, retail version

Return Value

Each of these functions, if successful, returns a handle 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 handles are available
ENOENT	The specified file could not be found

Parameters

filename

Name of new file

pmode

Permission setting

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 & _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:

_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. Thus the modes _S_IWRITE and _S_IREAD | _S_IWRITE are 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.

Example

/* 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>

void main( void )
{
   int fh;

   fh = _creat( "data", _S_IREAD | _S_IWRITE );
   if( fh == -1 )
      perror( "Couldn't create data file" );
   else
   {
      printf( "Created data file.\n" );
      _close( fh );
   }
}

Output

Created data file.

Low-Level I/O Routines

See Also   _chmod, _chsize, _close, _dup, _open, _sopen, _umask