creat() — Create a new file or rewrite an existing one

Standards

Standards / Extensions	C or C++	Dependencies
POSIX.1 XPG4 XPG4.2 Single UNIX Specification, Version 3	both

Format

#define _POSIX_SOURCE
#include <fcntl.h>

int creat(const char *pathname, mode_t mode);

General description

The function call: creat(pathname,mode) is equivalent to the call:

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

Thus the file named by pathname is created, unless it already exists. The file is then opened for writing only, and is truncated to zero length. See open() — Open a file for further information.

The mode argument specifies the file permission bits to be used in creating the file. Here is a list of symbols that can be used for a mode:

S_IRGRP: Read permission for the file's group.
S_IROTH: Read permission for users other than the file owner.
S_IRUSR: Read permission for the file owner.
S_IRWXG: Read, write, and search, or execute permission for the file's group. S_IRWXG is the bitwise inclusive-OR of S_IRGRP, S_IWGRP, and S_IXGRP.
S_IRWXO: Read, write, and search, or execute permission for users other than the file owner. S_IRWXO is the bitwise inclusive-OR of S_IROTH, S_IWOTH, and S_IXOTH.
S_IRWXU: Read, write, and search, or execute, for the file owner; S_IRWXG is the bitwise inclusive-OR of S_IRUSR, S_IWUSR, and S_IXUSR.
S_ISGID: Privilege to set group ID (GID) for execution. When this file is run through an exec function, the effective group ID of the process is set to the group ID of the file, so that the process has the same authority as the file owner rather than the authority of the actual invoker.
S_ISUID: Privilege to set the user ID (UID) for execution. When this file is run through an exec function, the effective user ID of the process is set to the owner of the file, so that the process has the same authority as the file owner rather than the authority of the actual invoker.
S_ISVTX: Indicates shared text. Keep loaded as an executable file in storage.
S_IWGRP: Write permission for the file's group.
S_IWOTH: Write permission for users other than the file owner.
S_IWUSR: Write permission for the file owner.
S_IXGRP: Search permission (for a directory) or execute permission (for a file) for the file's group.
S_IXOTH: Search permission for a directory, or execute permission for a file, for users other than the file owner.
S_IXUSR: Search permission (for a directory) or execute permission (for a file) for the file owner.

Large file support for z/OS UNIX files: Large z/OS UNIX files are supported automatically for AMODE 64 C/C++ applications. AMODE 31 C/C++ applications must be compiled with the option LANGLVL(LONGLONG) and define the _LARGE_FILES feature test macro before any headers are included to enable this function to operate on z/OS UNIX files that are larger than 2 GB in size. File size and offset fields are enlarged to 63 bits in width. Therefore, any other function operating on the file is required to define the _LARGE_FILES feature test macro as well.

Returned value

If successful, creat() returns a file descriptor for the open file.

If unsuccessful, creat() returns -1 and sets errno to one of the following values:

Error Code

Description

EACCES

One of the following error conditions exists:

The process did not have search permission on a component in pathname.
The file exists but the process did not have appropriate permissions to open the file in the way specified by the flags.
The file does not exist, and the process does not have write permission on the directory where the file is to be created.
O_TRUNC was specified, but the process does not have write permission on the file.

EINTR

open() was interrupted by a signal.

EISDIR

pathname is a directory, and options specifies write or read/write access.

ELOOP

A loop exists in symbolic links. This error is issued if the number of symbolic links detected in the resolution of pathname is greater than POSIX_SYMLOOP.

EMFILE

The process has reached the maximum number of file descriptors it can have open.

ENAMETOOLONG

pathname is longer than PATH_MAX characters or some component of pathname is longer than NAME_MAX characters while _POSIX_NO_TRUNC is in effect. For symbolic links, this error occurs if the length of a pathname string substituted for a symbolic link in the pathname argument exceeds PATH_MAX. The PATH_MAX and NAME_MAX values can be determined with pathconf().

ENFILE

The system has reached the maximum number of file descriptors it can have open.

ENOENT

O_CREAT is specified, and either the path prefix does not exist or the pathname argument is an empty string.

ENOSPC

The directory or file system intended to hold a new file has insufficient space.

ENOTDIR

A component of pathname is not a directory.

EOVERFLOW

The named file is a regular file and the size of the file cannot be represented correctly in an object of type off_t

EROFS

pathname is on a read-only file system.

Example

CELEBC28

/* CELEBC28

   This example creates a file.

 */
#define _POSIX_SOURCE
#include <fcntl.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <unistd.h>
#undef _POSIX_SOURCE
#include <stdio.h>

main() {
  char fn[]="creat.file", text[]="This is a test";
  int fd;

  if ((fd = creat(fn, S_IRUSR | S_IWUSR)) < 0)
    perror("creat() error");
  else {
    write(fd, text, strlen(text));
    close(fd);
    unlink(fn);
  }
return(fd);
}