creat()

create and open a file at the operating system level

Synopsis:

#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
int creat( const char *path, mode_t mode );

Description:

The creat() function creates (and opens) a file at the operating system level. It's equivalent to:

  open( path, O_WRONLY | O_CREAT | O_TRUNC, mode );

The name of the file to be created is given by path. When the file exists (it must be writable), it is truncated to contain no data, and the existing mode setting is not changed.

When the file doesn't exist, it is created with access permissions given by the mode argument. The access permissions for the file or directory are specified as a combination of bits. These are defined in the <sys/stat.h> header file, and are described in the section on this file in the Header Files chapter.

Returns:

If successful, creat() returns a descriptor for the file. When an error occurs while opening the file, -1 is returned, and errno is set to indicate the error.

Errors:

EACCES

Indicates one of the following problems with permissions:

• Search permission is denied on a component of the path prefix
• the file exists, and the permissions specified by mode are denied
• the file doesn't exist, and write permission is denied for the parent directory of the file to be created

EBADFSYS

While attempting to open the named file, either the file itself or a component of the path prefix was found to be corrupted. A system failure - from which no automatic recovery is possible - occurred while the file was being written to or while the directory was being updated. It will be necessary to invoke appropriate systems administrative procedures to correct this situation before proceeding.

EBUSY

The file named by path is a block special device that is already open for writing, or path names a file that is on a file system mounted on a block special device that is already open for writing.

EINTR

The creat() operation was interrupted by a signal.

EISDIR

The named file is a directory, and the file creation flags specify write-only or read/write access.

EMFILE

Too many file descriptors are currently in use by this process.

ENAMETOOLONG

The length of the path string exceeds PATH_MAX, or a pathname component is longer than NAME_MAX.

ENFILE

Too many files are currently open in the system.

ENOENT

Either the path prefix does not exist, or the path argument points to an empty string.

ENOSPC

The directory or file system that would contain the new file cannot be extended.

ENOTDIR

A component of the path prefix is not a directory.

EROFS

The named file resides on a read-only file system.

Examples:

#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>

void main()
  {
    int filedes;

    filedes = creat( "file",
                 S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP );
    if( filedes != -1 ) {

      /* process file */

      close( filedes );
    }
  }

Classification:

POSIX 1003.1

See also:

chsize(), close(), dup(), dup2(), eof(), errno, exec... functions, fcntl(), filelength(), fileno(), fstat(), isatty(), lseek(), open(), read(), setmode(), sopen(), stat(), tell(), write(), umask()