gtpc2m0pC/C++ Language Support User's Guide

chmod-Change the Mode of a File or Directory

This function changes the mode of a file or directory.

Format

#include <sys/stat.h>
int chmod(const char *pathname, mode_t mode);

pathname
The name of the file or directory whose access mode is to be changed.

mode
The mode parameter is created with one of the following symbols defined in the sys/stat.h header file. Any mode flags that are not specified will be turned off.

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.

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 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's 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.

S_IWOTH
Write permission for users other than the file owner.

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

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

This function changes the mode of the file or directory specified in pathname.

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). The chmod function automatically clears the S_ISGID bit in the file's mode bits if all the following conditions are true:

TPF deviation from POSIX

The TPF system does not support the ctime time stamp.

Normal Return

If successful, the chmod function returns 0.

Error Return

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

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. For symbolic links, the length of the pathname string substituted for a symbolic link exceeds PATH_MAX.

ENOENT
There is no file named pathname, or the pathname parameter is an empty string.

ENOTDIR
Some component of the pathname prefix is not a directory.

EPERM
The calling process does not have appropriate privileges. The UID of the calling process is neither zero nor the same UID as the file owner.

Programming Considerations

None.

Examples

The following example changes the permission from the file owner to the file group.

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

Related Information

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