utime()--Set File Access and Modification Times
Syntax
#include <utime.h> int utime(const char *path, const struct utimbuf *times);Service Program Name: QP0LLIB1
Default Public Authority: *USE
Threadsafe: Conditional; see Usage Notes.
The utime() function sets the access and modification times of path to the values in the utimbuf structure. If times is a NULL pointer, the access and modification times are set to the current time. If the named file is a symbolic link, utime() resolves the symbolic link.
If the file is checked out by another user (someone other than the user profile of the current job), utime() fails with the [EBUSY] error.
When utime() completes successfully, it marks the change time of the file to be updated.
Parameters
- path
- (Input) A pointer to the null-terminated path name of the file for which
the times should be changed.
This parameter is assumed to be represented in the CCSID (coded character set identifier) currently in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented in the default CCSID of the job.
See QlgUtime()--Set File Access and Modification Times (using NLS-enabled path name) for a description and an example of supplying the path in any CCSID.
- times
- (Input) A pointer to a structure utimbuf, which contains the times to be updated.
The structure utimbuf is defined according to the POSIX.1 definition as follows:
struct utimbuf { time_t actime; /* The new access time */ time_t modtime; /* The new modification time */ }
The time_t type gives the number of seconds since the Epoch.
Authorities
Note: Adopted authority is not used.
Authorization Required for utime() (excluding
QDLS)
Object Referred to | Authority Required | errno |
---|---|---|
Each directory in the path name preceding the object | *X | EACCES |
Object when changing the time to a specified value | Owner (See Note) | EPERM |
Object when changing the time to the current time | Owner or *W (See Note) | EACCES |
Note: You do not need the listed authority if you have *ALLOBJ special authority. |
Authorization Required for utime() in the QDLS
File System
Object Referred to | Authority Required | errno |
---|---|---|
Each directory in the path name preceding the object | *X | EACCES |
Object when changing the time to a specified value | *W | EPERM |
Object when changing the time to the current time | *W | EACCES |
Return Value
- 0
- utime() was successful. The file access and modification times are changed.
- -1
- utime() was not successful. The file times are not changed. The errno global variable is set to indicate the error.
Error Conditions
If utime() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.
Error condition | Additional information |
---|---|
[EACCES] |
If you are accessing a remote file through the Network File System, update operations to file permissions at the server are not reflected at the client until updates to data that is stored locally by the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) command determine the time between refresh operations of local data.) Access to a remote file may also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote systems. times is NULL and the job does not have authority to perform the requested function. |
[EAGAIN] | |
[EBADFID] | |
[EBADNAME] | |
[EBUSY] | |
[ECONVERT] | |
[EDAMAGE] | |
[EFAULT] | |
[EFILECVT] | |
[EINTR] | |
[EINVAL] | |
[EIO] | |
[EISDIR] | |
[EJRNDAMAGE] | |
[EJRNENTTOOLONG] | |
[EJRNINACTIVE] | |
[EJRNRCVSPC] | |
[ELOOP] | |
[ENAMETOOLONG] | |
[ENEWJRN] | |
[ENEWJRNRCV] | |
[ENOENT] | |
[ENOMEM] | |
[ENOSPC] | |
[ENOTAVAIL] | |
[ENOTDIR] | |
[ENOTSAFE] | |
[ENOTSUP] | |
[EPERM] |
times is not NULL and the thread does not have authority to perform the requested function. |
[EROOBJ] | |
[ESTALE] |
If you are accessing a remote file through the Network File System, the file may have been deleted at the server. |
[EUNKNOWN] |
If interaction with a file server is required to access the object, errno could indicate one of the following errors:
Error condition | Additional information |
---|---|
[EADDRNOTAVAIL] | |
[ECONNABORTED] | |
[ECONNREFUSED] | |
[ECONNRESET] | |
[EHOSTDOWN] | |
[EHOSTUNREACH] | |
[ENETDOWN] | |
[ENETRESET] | |
[ENETUNREACH] | |
[ESTALE] |
If you are accessing a remote file through the Network File System, the file may have been deleted at the server. |
[ETIMEDOUT] | |
[EUNATCH] |
Error Messages
The following messages may be sent from this function:
Message ID | Error Message Text |
---|---|
CPE3418 E | Possible APAR condition or hardware failure. |
CPFA0D4 E | File system error occurred. Error number &1. |
CPF3CF2 E | Error(s) occurred during running of &1 API. |
CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
Usage Notes
- This function will fail with error code [ENOTSAFE] when all the following
conditions are true:
- Where multiple threads exist in the job.
- The object on which this function is operating resides in a file system
that is not threadsafe. Only the following file systems are threadsafe for this
function:
- "Root" (/)
- QOpenSys
- User-defined
- QNTC
- QSYS.LIB
- Independent ASP QSYS.LIB
- QOPT
- Network File System
- QFileSvr.400
- Where multiple threads exist in the job.
- QSYS.LIB and Independent ASP QSYS.LIB File System Differences
These file systems do not support utime().
- QDLS File System Differences
Changing the times of the /QDLS directory (the root folder) is not allowed.
- QOPT File System Differences
The QOPT file system does not support utime().
- QNTC File System Differences
The QNTC file system does not set the access and modification times of path. The values in the utimbuf structure are ignored.
-
When you develop in C-based languages and this function is compiled with
_64_BIT_TIME defined, it will be mapped to utime_time64().
Note that the type of the times parameter, struct utimbuf *,
also will be mapped to type struct utimbuf_time64 *. See utime_time64() for more information about this structure.
Related Information
- The <utime.h> file (see Header
Files for UNIX®-Type Functions)
- The <limits.h> file (see Header
Files for UNIX-Type Functions)
- QlgUtime()--Set File Access and Modification Times (using NLS-enabled path name)
Example
The following example uses utime().
Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.
#include <utime.h> #include <time.h> #include <stdio.h> #include <sys/types.h> #include <sys/stat.h> #include <fcntl.h> main() { int file_descriptor; char fn[]="utime.file"; struct utimbuf ubuf; struct stat info; if ((file_descriptor = creat(fn, S_IWUSR)) < 0) perror("creat() error"); else { close(file_descriptor); puts("before utime()"); stat(fn,&info); printf(" utime.file modification time is %ld\n", info.st_mtime); ubuf.modtime = 0; /* set modification time to Epoch */ time(&ubuf.actime); if (utime(fn, &ubuf) != 0) perror("utime() error"); else { puts("after utime()"); stat(fn,&info); printf(" utime.file modification time is %ld\n", info.st_mtime); } unlink(fn); } }
Output:
before utime() utime.file modification time is 749323571 after utime() utime.file modification time is 0
API introduced: V3R1