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);
}