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.
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)Object Referred to | Authority Required | errno |
---|---|---|
Each directory in the path name preceding the object | *X | EACCES |
Object | Owner (see Note) | EPERM |
Note: You do not need the listed authority if you have *ALLOBJ special authority. |
Authorization required for chmod() in the QDLS File System
Object Referred to | Authority Required | errno |
---|---|---|
Each directory in the path name preceding the object | *X | EACCES |
Object | Owner or *ALL | EACCES |
Authorization required for chmod() in the QSYS.LIB and Independent ASP QSYS.LIB file systems.
Object Referred to | Authority Required | errno |
---|---|---|
Each directory in the path name preceding the object | *X | EACCES |
The parent directory of the object if the object is a save file | *RX | EPERM |
Object | Owner (see Note) | EPERM |
Note: You do not need the listed authority if you have *ALLOBJ special authority. |
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.
Error condition | Additional information |
---|---|
[EACCES] |
If you are accessing a remote file through the Network File System, update operations to file permissions at the server are not reflected at the client until updates to data that is stored locally by the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) command determine the time between refresh operations of local data.) Access to a remote file may also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote systems. |
[EAGAIN] | |
[EBADFID] | |
[EBADNAME] | |
[EBUSY] | |
[ECONVERT] | |
[EDAMAGE] | |
[EFAULT] | |
[EFILECVT] | |
[EINTR] | |
[EINVAL] | |
[EIO] | |
[EJRNDAMAGE] | |
[EJRNENTTOOLONG] | |
[EJRNINACTIVE] | |
[EJRNRCVSPC] | |
[ELOOP] | |
[ENAMETOOLONG] | |
[ENEWJRN] | |
[ENEWJRNRCV] | |
[ENOENT] | |
[ENOSPC] | |
[ENOTAVAIL] | |
[ENOTDIR] | |
[ENOTSAFE] | |
[ENOTSUP] | |
[EPERM] | |
[EROOBJ] | |
[ESTALE] |
If you are accessing a remote file through the Network File System, the file may have been deleted at the server. |
[EUNKNOWN] |
If interaction with a file server is required to access the object, errno could also indicate one of the following errors:
Error condition | Additional information |
---|---|
[EADDRNOTAVAIL] | |
[ECONNABORTED] | |
[ECONNREFUSED] | |
[ECONNRESET] | |
[EHOSTDOWN] | |
[EHOSTUNREACH] | |
[ENETDOWN] | |
[ENETRESET] | |
[ENETUNREACH] | |
[ETIMEDOUT] | |
[EUNATCH] |
Error Messages
The following messages may be sent from this function:
Message ID | Error Message Text |
---|---|
CPE3418 E | Possible APAR condition or hardware failure. |
CPFA0D4 E | File system error occurred. Error number &1. |
CPF3CF2 E | Error(s) occurred during running of &1 API. |
CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
Usage Notes
- 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
- Where multiple threads exist in the job.
- "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.
- 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.
- 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.
- 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.
- 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.
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.
- 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.
- 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.
- 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
API introduced: V3R1