chmod()--Change File Authorizations

 #include <sys/stat.h>

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

The chmod() function changes S_ISUID, S_ISGID, S_ISVTX, and the permission bits of the file or directory specified in path to the corresponding bits specified in mode. If the named file is a symbolic link, chmod() resolves the symbolic link. chmod() has no effect on file descriptions for files that are open at the time chmod() is called.

When chmod() is successful it updates the change time of the file.

If the file is checked out by another user (someone other than the user profile of the current job), chmod() fails with the [EBUSY] error.

Parameters

path

(Input) A pointer to the null-terminated path name of the file whose mode is being changed.

This parameter is assumed to be represented in the CCSID (coded character set identifier) currently in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented in the default CCSID of the job.

See QlgChmod()--Change File Authorizations for a description and an example of supplying the path in any CCSID.

mode

(Input) Bits that define S_ISUID, S_ISGID, S_ISVTX, and the access permissions of the file.

The mode argument can be one of the following symbols defined in the <sys/stat.h> include file, or constructed with a bitwise inclusive OR of two or more of these symbols.

See the Usage Notes for the file system differences regarding these symbols.

S_IRUSR

Read permission for the file owner

S_IWUSR

Write permission for the file owner

S_IXUSR

Search permission (for a directory) or execute permission (for a file) for the file owner

S_IRWXU

Read, write, and search or execute 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's group

S_IWGRP

Write permission for the file's group

S_IXGRP

Search permission (for a directory) or execute permission (for a file) for the file's group

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_IROTH

General read permission

S_IWOTH

General write permission

S_IXOTH

General search permission (for a directory) or general execute permission (for a file)

S_IRWXO

General read, write, and search or execute permission. S_IRWXO is the bitwise inclusive OR of S_IROTH, S_IWOTH, and S_IXOTH

S_ISUID

Set effective user ID at execution time. This bit is ignored if the object specified by path is a directory.

S_ISGID

Set effective group ID at execution time. See Usage Notes for more information if the object specified by path is a directory.

S_ISVTX

Restricted renames and unlinks for objects within a directory. Objects can be linked into a directory that has this bit set on, but cannot be renamed or unlinked from it unless one or more of the following are true for the user performing the operation:

• The user is the owner of the object.
• The user is the owner of the directory.
• The user has all object (*ALLOBJ) special authority.

This restriction only applies to directories in the "root" (/), QOpenSys, and user-defined file systems. Other types of object and directories in other file systems may have this bit on, however, it will be ignored.

If bits other than the bits listed above are set in mode, chmod() returns the [EINVAL] error.

Authorities

Note: Adopted authority is not used.

Return Value

0

chmod() was successful.

-1

chmod() was not successful. The errno global variable is set to indicate the error.

Error Conditions

If chmod() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

If interaction with a file server is required to access the object, errno could also indicate one of the following errors:

Error Messages

The following messages may be sent from this function:

Usage Notes

1. This function will fail with error code [ENOTSAFE] when all the following conditions are true:
   
   
   • Where multiple threads exist in the job.
     
   • The object on which this function is operating resides in a file system that is not threadsafe. Only the following file systems are threadsafe for this function:
     
     
     • "Root" (/)
     • QOpenSys
     • User-defined
     • QNTC
     • QSYS.LIB
     • Independent ASP QSYS.LIB
     • QOPT
     • Network File System
     • QFileSvr.400
   
   
2. "Root" (/), QOpenSys, and User-Defined File System Differences

   If the object has a primary group, it must match the primary group ID or one of the supplemental group IDs of the caller of the API; otherwise, the S_ISGID bit is turned off.

   
   
3. QSYS.LIB and independent ASP QSYS.LIB File System Differences

   chmod() is not supported for member (.MBR) objects.

   chmod() returns EBUSY if the object is allocated in another job.

   QSYS.LIB and independent ASP QSYS.LIB do not support setting the S_ISUID (set-user-ID), S_ISGID (set-group_ID), and S_ISVTX (restricted rename and unlink) bits. If they are turned on in the mode parameter, they are ignored.

   
   
4. QDLS File System Differences

   Changing the permissions of the /QDLS directory (the root folder) is not allowed. If an attempt is made to change the permissions, error ENOTSUP is returned.

   "Group" rights are not set if there is no current group.

   QDLS does not support setting the S_ISUID, S_ISGID, and S_ISVTX bits. If they are turned on in the mode parameter, they are ignored.

   
   
5. QOPT File System Differences

   Changing the permissions is allowed only for an object that exists on a volume formatted in Universal Disk Format (UDF). For all other media formats, ENOTSUP is returned.

   In addition to the authorization checks described in Authorization Required for chmod(), the volume authorization list is checked for *CHANGE authority.

   QOPT does not support setting the S_ISUID, S_ISGID, and S_ISVTX bits for any optical media format. If they are turned on in the mode parameter, ENOTSUP is returned.

   
   
6. QFileSvr.400 Differences

   QFileSvr.400 supports the S_ISUID, S_ISGID, and S_ISVTX bits by passing them to the server and surfacing them to the caller.

   
   
7. Network File System Differences

   The NFS client supports the S_ISUID, S_ISGID, and S_ISVTX bits by passing them to the server over the network and surfacing them to the caller. Whether a particular network file system supports the setting of these bits depends on the server. Most servers have the capability of masking off the S_ISUID and S_ISGID bits if the NOSUID option is specified on the export. The default, however, is to support these two bits.

   
   
8. QNTC File System Differences

   chmod() does not update the Windows NT^® server access control lists that control the authority of users to the file or directory. The mode settings are ignored.

   
   
9. S_ISGID bit of a directory in "root" (/), QOpenSys, or User-Defined File System

   The S_ISGID bit of the directory affects what the group ID (GID) is for objects that are created in the directory. If the S_ISGID bit of the parent directory is off, the group ID (GID) is set to the effective GID of the thread creating the object. If the S_ISGID bit of the parent directory is on, the group ID (GID) of the new object is set to the GID of the parent directory. For all other file systems, the GID of the new object is set to the GID of the parent directory.

Related Information

• The <sys/types.h> file (see Header Files for UNIX^®-Type Functions)
• The <sys/stat.h> file (see Header Files for UNIX-Type Functions)
• chown()--Change Owner and Group of File
• fchmod()--Change File Authorizations by Descriptor
• mkdir()--Make Directory
• open()--Open File
• stat()--Get File Information
• QlgChmod()--Change File Authorizations

Example

The following example changes the permissions for a file.

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

#include <stdio.h>
#include <sys/stat.h>
#include <sys/types.h>

main() {
  char fn[]="temp.file";
  int file_descriptor;
  struct stat info;

  if ((file_descriptor = creat(fn, S_IWUSR)) == -1)
    perror("creat() error");
  else {
    if (stat(fn, &info)!= 0)
       perror("stat() error");
    else {
      printf("original permissions were: %08o\n", info.st_mode);
    }
    if (chmod(fn, S_IRWXU|S_IRWXG) != 0)
      perror("chmod() error");
    else {
      if (stat(fn, &info)!= 0)
         perror("stat() error");
      else { 
         printf("after chmod(), permissions are: %08o\n", info.st_mode);
      }
    }
    if (close(file_descriptor)!= 0)
       perror("close() error");
    if (unlink(fn)!= 0)
       perror("unlink() error");
  }
}

Output:

original permissions were: 00100200
after chmod(), permissions are: 00100770

[ Back to top | UNIX-Type APIs | APIs by category ]