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

Function

The chmod service modifies the permission bits that are used to control the owner access, group access, and general access to a file. You can use it to set flags that modify the user ID (UID) and group ID (GID) of the file when it is executed. You can also use it to set the sticky bit to indicate from where the file should be fetched. You identify the file by its pathname.

For the corresponding service using a file descriptor, see fchmod (BPX1FCM, BPX4FCM) — Change the mode of a file or directory by descriptor.

Requirements

Parameters

Pathname_length

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the length of the pathname of the file whose mode you want to change.

Pathname

Supplied parameter

Type:

Character string

Character set:

No restriction

Length:

Specified by the Pathname_length parameter

The name of a field that contains the pathname of the file. This field has the length that is specified in Pathname_length.

Pathnames can begin with or without a slash.

• A pathname that begins with a slash is an absolute pathname. The slash refers to the root directory, and the search for the file starts at the root directory.
• A pathname that does not begin with a slash is a relative pathname. The search for the file starts at the working directory.

Mode

Supplied parameter

Type:

Structure

Length:

Fullword

The name of a fullword that describes the access. This field, which is mapped by BPXYMODE, specifies the file type and permissions for the caller, for the callers group, and for any others. For more information, see BPXYMODE — Map the mode constants of the file services.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the chmod service returns 0 if the request is successful, or -1 if it is not successful.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the chmod service stores the return code. The chmod service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The chmod service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EACCES	The calling process does not have permission to search some component of Pathname.
ELOOP	A loop exists in symbolic links that were encountered during resolution of the Pathname argument. This error is issued if more than 24 symbolic links are detected in the resolution of Pathname.
ENAMETOOLONG	Pathname is longer than 1023 characters, or a component of the pathname is longer than 255 characters. Filename truncation is not supported.
ENOENT	No file named Pathname was found, or no pathname was specified. The following reason code can accompany the return code: JRFileNotThere.
ENOTDIR	Some component of Pathname is not a directory.
EPERM	The effective UID of the calling process does not match the owner of the file, and the calling process does not have appropriate privileges (see Authorization).
EROFS	Pathname specifies a file that is on a read-only file system. The following reason code can accompany the return code: JRReadOnlyFS.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the chmod service stores the reason code. The chmod service returns a Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. See z/OS UNIX System Services Messages and Codes for the reason codes.

Usage notes

1. File descriptors that are open when the chmod service is called retain the access permission they had when the file was opened.
2. For mode bits to be changed, the effective UID of the calling process must match the file's owner UID, or the caller must have appropriate privileges (see Authorization).
3. A user with READ authority to SUPERUSER.FILESYS.CHANGEPERMS in the UNIXPRIV class can use the chmod service to change the permission bits of any file.
4. When the mode is changed successfully, the file's change time is also updated.
5. Setting the set-group-ID-on-execution permission means that when this file is run, through the exec, spawn, or attach_exec service, the effective GID of the caller is set to the file's owner GID, so that the caller seems to be running under the GID of the file rather than that of the actual invoker.
   The set-group-ID-on-execution permission is set to zero if both of the following are true:

   • The caller does not have appropriate privileges.
   • The GID of the file's owner does not match the effective GID, or one of the supplementary GIDs, of the caller.
6. Setting the set-user-ID-on-execution permission means that when this file is run, the process's effective UID is set to the file's owner UID, so that the process seems to be running under the UID of the file's owner, rather than that of the actual invoker.

Related services

• chown (BPX1CHO, BPX4CHO) — Change the owner or group of a file or directory
• fchmod (BPX1FCM, BPX4FCM) — Change the mode of a file or directory by descriptor
• mkdir (BPX1MKD, BPX4MKD) — Make a directory
• open (BPX1OPN, BPX4OPN) — Open a file
• stat (BPX1STA, BPX4STA) — Get status information about a file by pathname

Characteristics and restrictions

There are no restrictions on the use of the chmod service.