gtpc2m12C/C++ Language Support User's Guide

creat-Create a New File or Rewrite an Existing File

This function creates a new file or rewrites an existing one.

Format

#include <fcntl.h>
int creat(const char *pathname, mode_t mode);

pathname
The name of the file to be created.

mode
The mode parameter specifies the file permission bits to be used in creating the file. The following is a list of symbols that you can use for a mode.

S_ISUID
Privilege to set the user ID (UID) to run. When this file is run through the tpf_fork function, the effective user ID of the process is set to the owner of the file. The process then has the same authority as the file owner rather than the authority of the actual caller.

S_ISGID
Privilege to set the group ID (GID) to run. When this file is run through the tpf_fork function, the effective group ID of the process is set to the group of the file. The process then has the same authority as the file group rather than the authority of the actual caller. If pathname is a regular file and the calling process is not running as superuser (its effective UID is not 0), the S_ISUID and S_ISGID flags for the file are cleared to zeros.

S_IRUSR
Read permission for the file owner.

S_IWUSR
Write permission for the file owner.

S_IXUSR
Search permission (for a directory) for the file owner.

S_IRWXU
Read, write, and search permission for the file owner; S_IRWXU is the bitwise inclusive OR of S_IRUSR, S_IWUSR, and S_IXUSR.

S_IRGRP
Read permission for the file group.

S_IWGRP
Write permission for the file group.

S_IXGRP
Search permission (for a directory) for the file group.

S_IRWXG
Read, write, and search permission for the file group. S_IRWXG is the bitwise inclusive OR of S_IRGRP, S_IWGRP, and S_IXGRP.

S_IROTH
Read permission for users other than the file owner or group.

S_IWOTH
Write permission for users other than the file owner or group.

S_IXOTH
Search permission for a directory for users other than the file owner or group.

S_IRWXO
Read, write, and search permission for users other than the file owner or group. S_IRWXO is the bitwise inclusive OR of S_IROTH, S_IWOTH, and S_IXOTH.

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

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

Therefore, 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 more information.

Normal Return

If the creat function is successful, it returns a file descriptor for the open file.

Error Return

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

EACCES

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.

For symbolic links, the length of the pathname string substituted for a symbolic link exceeds PATH_MAX.

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

ENOENT
Either the path prefix does not exist or the pathname parameter is an empty string.

ENOSPC
The directory or file system that intended to hold a new file does not has enough space.

ENOTDIR
A component of pathname is not a directory.

Programming Considerations

Examples

The following example creates a file.

#include <fcntl.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <unistd.h>
#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);
  }
}

Related Information

See Appendix E, Programming Support for the TPF File System for more information about TPF File System C Functions.