NAME

zkChmod - change mode of a file

SYNOPSIS

#include "zkSysStat.h"

int zkChmod(const char *path, mode_t mode);

DESCRIPTION

The zkChmod() function changes the file permission bits of the file named by the pathname pointed to by the path argument to the corresponding bits in the mode argument. The process must have appropriate privileges in order to do this. The definition of "appropriate privileges" is implementation-defined.

The file permission bits are described in "zkSysStat.h".

The effect on file descriptors for files open at the time of a call to zkChmod() is implementation-dependent.

RETURN VALUE

Upon successful completion, 0 is returned. Otherwise, -1 is returned and errno is set to indicate the error. If -1 is returned, no change to the file mode will occur.

ERRORS

The zkChmod() function will fail if:

[EACCES]
Search permission is denied on a component of the path prefix.
[ELOOP]
Too many symbolic links were encountered in resolving path.
[ENAMETOOLONG]
The length of the path argument exceeds {PATH_MAX} or a pathname component is longer than {NAME_MAX}.
[ENOTDIR]
A component of the path prefix is not a directory.
[ENOENT]
A component of path does not name an existing file or path is an empty string.
[EPERM]
The effective user ID does not match the owner of the file and the process does not have appropriate privileges.
[EROFS]
The named file resides on a read-only file system.

The zkChmod() function may fail if:

[EINTR]
A signal was caught during execution of the function.
[EINVAL]
The value of the mode argument is invalid.
[ENAMETOOLONG]
Pathname resolution of a symbolic link produced an intermediate result whose length exceeds {PATH_MAX}.

PORTABILITY

Implementations may allow other bits in mode to be set. For example, on UNIX systems, the S_ISUID, S_ISGID, S_ISVTX bits may be set. Some implementations may allow zkChmod() to be called on things other than regular files (directories, for example). All of these features are non-portable.

Any file descriptors currently open by any process on the file may become invalid if the mode of the file is changed to a value which would deny access to that process. One situation where this could occur is on a stateless file system.

Persons intending to call zkChmod() in their code are encouraged to read the system documentation for their target platforms.