_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.
See Also _chmod, _chsize, _close, _dup, _open, _sopen, _umask