utime

Sets access and modification times of a file.

Syntax

   #include <sys/types.h>

   #include <utime.h> 

   int utime(const char *path, const struct utimbuf *times),

Parameters

path

A pointer to a character array containing the pathname of the file that is to become the new process image. The pathname must be terminated by a null character.

times

If not NULL, a pointer to a utimbuf structure containing the access and modification times. Only the owner of the file, the system manager, or the account manager can use the utime function this way.

If this argument is NULL, however, the access and modification time of the file are set to the current time.

Return Values

0: Successful completion.
-1: Error. errno is set to indicate the error, and the file times shall not be affected.

Description

The utime() function sets the access and modification times of the named file.

If the utime argument is NULL, the access and modification times of the file are set to the current time. The effective user ID of the process must match the owner of the file, or the process must have write permission to the file or appropriate privileges, to use the utime() function in this manner.

If the utime argument is not NULL, it is interpreted as a pointer to a utimbuf structure, and the access and modification times are set to the values contained in the designated structure. Only the owner of the file and processes weith appropriate privileges shall be permitted to use the utime() function in this way.

The utimbuf structure is defined by the header <utime.h> and includes the following members:

Member Type	Member Name	Description
`time_t`	`actime`	Access time
`time_t`	`modtime`	Modification time

The times the utimbuf structure are measured in seconds since the Epoc.

Upon successful completion, the utime() function shall mark for update the st_ctime field of the file.

Implementation Considerations

On the HP 3000, file times are updated at file close, not file open as with many other platforms. Therefore, a utime() call must follow an explicit close() call to change file times. This also means not allowing an implicit file close at the end of execution.

Based on the MPE/iX file system security, this implementation defines that the appropriate privilege which allows the calling process to use the utime function to modify time stamps is either the SM (System Manager) capability or AM capability for the specified file, i.e., the calling process' GID matches the file's GID.

An error condition was added to indicate that a file or directory is inaccessible because the ACD associated with it does not have write access, or to designate that a pathname that begins with two slashes was detected. Such pathnames are reserved by this implementation for future consideration.

Errors

If any of the following conditions occur, the utime() function will return -1 and set errno to the corresponding value.

`EACCES`	CAUSE	One of the following: The calling process does not have search permission to a component of the pathname. The calling process does not have execute permission to the file. The file is not a valid executable file.
	ACTION	One of the following: Make sure that the calling process has search permission to all components of the pathname. Make sure that the calling process has execute permission to the file. Make sure that the file has an MPE/iX file code of `NMPRG`.
`ENAMETOOLONG`	CAUSE	One of the following: The length of the pathname exceeds the `{PATH_MAX}` limit (defined in the file `<limits.h>`). A component of the pathname is longer than `{NAME_MAX}` (defined in `<limits.h>`), and `{_POSIX_NO_TRUNC}` is in effect for that directory.
	ACTION	Make sure that both the component's length and the full pathname length do not exceed the `{NAME_MAX}` or `{PATH_MAX}` limits.
`ENOTDIR`	CAUSE	A component of the pathname is not a directory.
	ACTION	Specify a valid pathname.
`ENOENT`	CAUSE	a component of the pathname for the executable file does not exist, or `pathname` points to an empty string.
	ACTION	Specify a valid pathname.
`EPERM`	CAUSE	One of the following: The calling process does not have the MPE/iX process handling (PH) capability. The calling process has outstanding switches to CM code, has set critical mode, has outstanding NOWAITIO, or is holding an operating system internal resource.
	ACTION	One of the following: Link the program file with the MPE/iX PH capability. Do not execute `execl()` when the calling process has outstanding switches to CM code, has set critical mode, has outstanding NOWAITIO, or is holding an operating system internal resource.
`EROFS`	CAUSE	The named file resides on a read-only file system.
	ACTION	Do not attempt to set the times for the file.

utime

Technical documentation

» Table of Contents

» Index