fchown (BPX1FCO, BPX4FCO) — Change the owner and group of a file or directory by descriptor
Function
The fchown callable service changes the owner, group, or both owner and group of a file. You identify the file by its file descriptor.
For the corresponding service using a pathname, see chown (BPX1CHO, BPX4CHO) — Change the owner or group 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 (BPX1FCO): | 31-bit |
AMODE (BPX4FCO): | 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
|
AMODE 64 callers use BPX4FCO with the same parameters.
Parameters
- File_descriptor
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword that contains the file descriptor of the file for which you wish to change the owner, group, or both owner and group.
- Owner_UID
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword field that contains the new owner UID assigned to the file, or the present value or -1 if there is no change. This parameter must be specified.
- Group_ID
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword field that contains the new group ID (GID) to be assigned to the file, or the present value or -1 if there is no change. This parameter must be specified.
- Return_value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword to which the fchown service returns 0 if the request is successful, or -1 if it is unsuccessful.
- Return_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the fchown service stores the return code. The fchown 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 fchown 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. EINVAL The Owner_UID or Group_ID parameter is incorrect; or File_descriptor refers to an unnamed pipe, and fchown is not allowed on such a file. EPERM 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 in which the fchown service stores the reason code. The fchown 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
- The fchown service changes the owner UID and owner GID of a file. Only a process with appropriate privileges (see Authorization) can change the owner UID of a file.
- The owner GID of a file can be changed by a process if the process
has appropriate privileges, or if a process meets all of these conditions:
- The effective UID of the process matches the file's owner UID.
- The Owner_UID value specified in the change request matches the file's owner UID.
- The Group_ID value specified in the change request is the effective GID, or one of the supplementary GIDs, of the calling process.
- The set-user-ID-on-execution and set-group-ID-on-execution permissions of the file mode are automatically turned off.
- If the change request is successful, the change time for the file is updated.
- Values for both Owner_UID and Group_ID must be specified. If you want to change only one of these values, you must set the other to its present value or to -1 in order for it to remain unchanged.
Related services
Characteristics and restrictions
There are no restrictions on the use of the fchown service.
Examples
See BPX1FCO (fchown) example for an example using this callable service.