_creat

Description

Creates a new file.

#include <sys\types.h>    
#include <sys\stat.h>    
#include <errno.h>    
#include <io.h> Required only for function declarations  

int _creat( char *filename, int pmode );

filename Path name of new file  
pmode Permission setting  

Remarks

The _creat function either creates a new file or opens and truncates an existing file. 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 of the constants are given, they are joined with the bitwise-OR operator (|). The pmode argument is set to one of the following values:

Value Meaning

_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. Note that all files are always readable; it is not possible to give write-only permission. Thus, the modes _S_IWRITE and _S_IREAD|_S_IWRITE are equivalent. With DOS versions 3.0 and later, files opened using _creat are always opened in compatibility mode (see _sopen). With DOS32X, the files are always opened with _SH_DENYNO.

The _creat function applies the current file-permission mask to pmode before setting the permissions (see _umask).

Note that the _creat routine is provided primarily for compatibility with previous libraries. A call to _open with _O_CREAT and _O_TRUNC in the oflag argument is equivalent to _creat and is preferable for new code.

Return Value

If successful, _creat returns a handle for the created file. Otherwise, it returns –1 and sets errno to one of the following constants:

Value Meaning

EACCES Path name specifies an existing read-only file or specifies a directory instead of a file
EMFILE No more handles available (too many open files)
ENOENT Path name not found

Compatibility

Standards:UNIX

16-Bit:DOS, QWIN, WIN, WIN DLL

32-Bit:DOS32X

Use _creat for compatibility with ANSI naming conventions of non-ANSI functions. Use creat and link with OLDNAMES.LIB for UNIX compatibility.

See Also

_chmod, _chsize, _close, _dup, _dup2, _open, _sopen, _umask

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.