chmod() — Change the mode of a file or directory

Standards

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

Format

#define _POSIX_SOURCE
#include <sys/stat.h>

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

General description

Changes the mode of the file or directory specified in pathname.

The mode argument is created with one of the following symbols defined in the sys/stat.h header file.

Any mode flags that are not defined will be turned off, and the function will be allowed to proceed.

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. The process then 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. The process then has the same authority as the file owner, rather than the authority of the actual invoker.
S_ISVTX: The sticky bit indicating 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.

Special behavior for XPG4.2: If a directory is writable and the mode bit S_ISVTX is set on the directory, a process may remove or rename files within that directory only if one or more of the following is true:

The effective user ID of the process is the same as that of the owner ID of the file.
The effective user ID of the process is the same as that of the owner ID of the directory.
The process has appropriate privileges.

A process can set mode bits only if the effective user ID of the process is the same as the file's owner or if the process has appropriate privileges (superuser authority). chmod() automatically clears the S_ISGID bit in the file's mode bits if all these conditions are true:

The calling process does not have appropriate privileges, that is, superuser authority (UID=0).
The group ID of the file does not match the group ID or supplementary group IDs of the calling process.
One or more of the S_IXUSR, S_IXGRP, or S_IXOTH bits of the file mode are set to 1.

Returned value

If successful, chmod() marks for update the st_ctime field of the file and returns 0.

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

Error Code: Description
EACCES: The process does not have search permission on some component of the pathname prefix.
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 (a value defined in the limits.h header file).
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, the length of the pathname string substituted for a symbolic link exceeds PATH_MAX. The PATH_MAX and NAME_MAX values are determined using pathconf().
ENOENT: There is no file named pathname, or the pathname argument is an empty string.
ENOTDIR: Some component of the pathname prefix is not a directory.
EPERM: The effective user ID (UID) of the calling process does not match the owner of the file, and the calling process does not have appropriate privileges (superuser authority).
EROFS: pathname is on a read-only file system.

Example

CELEBC11

⁄* CELEBC11

   This example changes the permission from the file owner to the file's
   group.

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

main() {
  char fn[]=".⁄temp.file";
  FILE *stream;
  struct stat info;

  if ((stream = fopen(fn, "w")) == NULL)
    perror("fopen() error");
  else {
    fclose(stream);
    stat(fn, &info);
    printf("original permissions were: %08x\n", info.st_mode);
    if (chmod(fn, S_IRWXU|S_IRWXG) != 0)
      perror("chmod() error");
    else {
      stat(fn, &info);
      printf("after chmod(), permissions are: %08x\n", info.st_mode);
    }
    unlink(fn);
  }
}

Output

original permissions were: 030001b6
after chmod(), permissions are: 030001f8