fchmod (BPX1FCM, BPX4FCM) — Change the mode of a file or directory by descriptor

Function

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

For the corresponding service using a pathname, see chmod (BPX1CHM, BPX4CHM) — Change the mode of a file or directory.

Requirements

Operation Environment
Authorization: Supervisor state or problem state, any PSW key
Dispatchable unit mode: Task
Cross memory mode: PASN = HASN
AMODE (BPX1FCM): 31-bit
AMODE (BPX4FCM): 64-bit
ASC mode: Primary address space control (ASC) mode
Interrupt status: Enabled for interrupts
Locks: Unlocked
Control parameters: All parameters must be addressable by the caller and in the primary address space.

Format

CALL BPX1FCM,(File_descriptor,
              Mode,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4FCM with the same parameters.

Parameters

File_descriptor
Supplied parameter
Type:
Integer
Length:
Fullword

Specifies the name of a fullword containing the file descriptor of the file whose mode you want to change.

Mode
Supplied parameter
Type:
Structure
Length:
Fullword

Specifies the name of a fullword in which the mode field is specified. The mode field, mapped by BPXYMODE, specifies the file type and the permissions you grant to yourself, to your group, and to any user. See BPXYMODE — Map the mode constants of the file services for the parameter options.

Return_value
Returned parameter
Type:
Integer
Length:
Fullword

Specifies the name of a fullword to which the fchmod service returns 0 if successful, or -1 if not successful.

Return_code
Returned parameter
Type:
Integer
Length:
Fullword
The name of a fullword in which the fchmod service stores the return code. The fchmod 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 fchmod service can return one of the following values in the Return_code parameter:
Return_code Explanation
EBADF The File_descriptor parameter is not a valid file descriptor.
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 The specified file 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 where the fchmod service stores the reason code. The fchmod 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 open at the time of the call to the fchmod service retain the access permission they had at the time 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 process must have appropriate privileges (see Authorization).
  3. When the mode is changed successfully, the file's change time is updated as well.
  4. Setting the set-group-ID-on-execution permission means that when this file is run, through the exec call, the effective GID of the process is set to the file's owner GID, so that the process 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 suppressed (the bit is turned off) if both of the following are true:
    • The calling process does not have appropriate privileges.
    • The file's owner GID does not match the effective GID or one of the supplementary GIDs of the calling process.
  5. Setting the set-user-ID-on-execution permission means that when this file is run the process's effective UID will be 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

Characteristics and restrictions

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

Examples

For an example using this callable service, see BPX1FCM (fchmod) example.

Parent topic: Callable services descriptions