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
CALL BPX1FCO,(File_descriptor,
Owner_UID,
Group_ID,
Return_value,
Return_code,
Reason_code)
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
. For a list of return code values, see Return codes (errnos) in z/OS UNIX System Services Messages and Codes. 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. For a list of reason codes, see Reason codes in z/OS UNIX System Services Messages and 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.