utime (BPX1UTI, BPX4UTI) — Set file access and modification times
Function
The utime callable service sets the access and modification times of a file.
Requirements
| Operation | Environment |
|---|---|
| Authorization: | Supervisor state or problem state, any PSW key |
| Dispatchable unit mode: | Task |
| Cross memory mode: | PASN = HASN |
| AMODE (BPX1UTI): | 31-bit |
| AMODE (BPX4UTI): | 64-bit |
| ASC mode: | Primary 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
The syntax format is as follows:
|
AMODE 64 callers use BPX4UTI with the same parameters. The Newtimes parameter is two doublewords.
Parameters
- Pathname_length
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword that contains the length of the fully qualified name (path name) of the file. The path name can be up to 1023 bytes long.
- Pathname
- Supplied parameter
- Type:
- Character string
- Character set:
- No restriction
- Length:
- Specified by the Pathname_length parameter
The name of a field of length Pathname_length that contains the pathname of the file.
Path names can begin with or without a slash.- A path name 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 path name that does not begin with a slash is a relative pathname. The search for the file starts at the working directory.
- Newtimes
- Supplied parameter
- Type:
- Structure
- Length:
- Doubleword (two doublewords)
The name of a doubleword or two doublewords that contain the access and modification times for the file. The first fullword (doubleword) contains the new access time, and the second fullword (doubleword) contains the new modification time. These times can be retrieved with stat (BPX1STA, BPX4STA) — Get status information about a file by pathname or fstat (BPX1FST, BPX4FST) — Get status information about a file by descriptor.- Times are specified as the number of seconds that have elapsed between 00:00 a.m. on January 1, 1970, and the desired time. The times must be specified as nonnegative values other than -1 (see this topic for the special case of -1). AMODE 64 callers must specify each time as a doubleword. Times beyond the year 2038 require more than a fullword.
- In order to request that the current time be used for both access and modification times, specify X'FFFFFFFF' or X'FFFFFFFFFFFFFFFF' (-1) in either or both words (doublewords) of this field. The current time in the file's status is also updated.
- Return_value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the utime 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 utime service stores the return code. The utime 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 utime service can return one of the following values in the Return_code parameter:Return_code Explanation EACCES One of the following is true: - The process does not have search permission for some component of the Pathname prefix.
- Newtimes equals the current time; the effective ID does not match the file's owner; the process does not have write permission for the file; and the process does not have appropriate privileges (see Authorization).
EINVAL The argument that was supplied is incorrect. The following reason code can accompany the return code: JRNegativeValueInvalid. 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 The length of the path name is greater than 1023, or some component of the fully qualified name is longer than 255 bytes. This could be as a result of encountering a symbolic link during resolution of Pathname, where the substituted string is longer than 1023 characters. ENOENT No file named Pathname was found; or Pathname was blank. The following reason code can accompany the return code: JRFileNotThere. ENOTDIR Some component of the path name prefix is not a directory. EPERM The Newtimes value did not specify the current time; the effective user ID 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 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 utime service stores the reason code. The utime service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For the reason codes, see z/OS UNIX System Services Messages and Codes.
Related services
Characteristics and restrictions
There are no restrictions on the use of the utime service.
Examples
For an example using this callable service, see BPX1UTI (utime) example.