_creat, _wcreat

Creates a new file.

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

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

For additional compatibility information, see Compatibility in the Introduction.

Libraries

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.

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

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