chmod()--Change File Authorizations


  Syntax
 #include <sys/stat.h>

 int chmod(const char *path, mode_t mode);  
  Service Program Name: QP0LLIB1

  Default Public Authority: *USE

  Threadsafe: Conditional; see Usage Notes.

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.

Authorization required for chmod() (excluding QDLS, QSYS.LIB, and Independent ASP QSYS.LIB)


Authorization required for chmod() in the QDLS File System


Authorization required for chmod() in the QSYS.LIB and Independent ASP QSYS.LIB file systems.


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.

    Start of change When changing the mode for the /QFileSvr.400 directory itself, only the permission bits are allowed. The group rights are ignored. If an attempt is made to set other bits, error ENOTSUP is returned. End of change


  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


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


API introduced: V3R1

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