### creat -- Create New File

Format

>     #include <io.h>
>     #include <sys\stat.h>
>     int creat(char *pathname, int pmode);

Language Level: XPG4, Extension
creat either creates a new file or opens and truncates an existing file. If the file specified by pathname does not exist, creat creates a new file with the given permission setting and opens it for writing in text mode. If the file already exists, and the read-only attribute and sharing permissions allow writing, creat truncates the file to length 0. This action destroys the previous contents of the file and opens it for writing in text mode. creat always opens a file in text mode for reading and writing.

The permission setting pmode applies to newly created files only. The new file receives the specified permission setting after you close it for the first time. The pmode integer expression contains one or both of the constants S_IWRITE and S_IREAD, defined in <sys\stat.h>. The values of the pmode argument and their meanings are:

Value | Meaning
S_IREAD | Reading permitted
S_IWRITE | Writing permitted
S_IREAD | S_IWRITE | Reading and writing permitted

If you do not give permission to write to the file, it is a read-only file. You cannot give write-only permission, thus the modes S_IWRITE and S_IREAD | S_IWRITE have the same results. The creat function applies the current file permission mask to pmode before setting the permissions.

When writing new code, you should use open rather than creat.

Specifying a pmode of S_IREAD is similar to making a file read-only with the ATTRIB system command.

Note: In earlier releases of the C/C++ run-time library, creat began with an underscore (_creat). Because it is defined by the X/Open standard, the underscore has been removed. For compatibility, IBM C and C++ Compilers will map _creat to creat for you.

Return Value
creat returns a handle for the created file if the call is successful. A return value of -1 shows an error, and creat sets errno to one of the following values:

Value | Meaning
EACCESS | File sharing violated.
EINVAL | The mode specified was not valid.
EMFILE | No more file handles are available.
ENOENT | The path name was not found, or the file name was incorrect.
EOS2ERR | The call to the operating system was not successful.

Example
This example creates the file sample.dat so it can be read from and written to.

    #include <sys\stat.h>
    #include <io.h>
    #include <stdio.h>
    #include <stdlib.h>

    int main(void)
    {
       int fh;

       fh = creat("sample.dat", S_IREAD|S_IWRITE);
       if (-1 == fh) {
          perror("Error in creating sample.dat");
          return EXIT_FAILURE;
       }
       else
          printf("Successfully created sample.dat.\n");
       close(fh);
       return 0;

       /***********************************************
          The output should be:

          Successfully created sample.dat.
       ***********************************************/
    }

chmod -- Change File Permission Setting
close -- Close File Associated with Handle
open -- Open File
fdopen -- Associates Input Or Output With File
_sopen -- Open Shared File
umask -- Set File Mask of Current Process
<sys\stat.h>
<io.h>