Function fchmodat [src]

Changes the mode of path relative to the directory referred to by dirfd. The process must have the correct privileges in order to do this successfully, or must have the effective user ID matching the owner of the file. On Linux the fchmodat2 syscall will be used if available, otherwise a workaround using procfs will be employed. Changing the mode of a symbolic link with AT.SYMLINK_NOFOLLOW set will also return OperationNotSupported, as: Permissions on the link are ignored when resolving its target. This operation has been known to invoke undefined behaviour across different filesystems[1]. [1]: https://sourceware.org/legacy-ml/libc-alpha/2020-02/msg00467.html.

Prototype

pub inline fn fchmodat(dirfd: fd_t, path: []const u8, mode: mode_t, flags: u32) FChmodAtError!void

Parameters

dirfd: fd_tpath: []const u8mode: mode_tflags: u32

Possible Errors

AccessDenied FChmodError

FileNotFound FChmodError

InputOutput FChmodError

NameTooLong

A component of path exceeded NAME_MAX, or the entire path exceeded PATH_MAX.

OperationNotSupported

path resolves to a symbolic link, and AT.SYMLINK_NOFOLLOW was set in flags. This error only occurs on Linux, where changing the mode of a symbolic link has no meaning and can cause undefined behaviour on certain filesystems.

The procfs fallback was used but procfs was not mounted.

PermissionDenied FChmodError

ProcessFdQuotaExceeded

The procfs fallback was used but the process exceeded its open file limit.

ReadOnlyFileSystem FChmodError

SymLinkLoop FChmodError

SystemFdQuotaExceeded

The procfs fallback was used but the system exceeded it open file limit.

SystemResources FChmodError

Unexpected UnexpectedError

The Operating System returned an undocumented error code.

This error is in theory not possible, but it would be better to handle this error than to invoke undefined behavior.

When this error code is observed, it usually means the Zig Standard Library needs a small patch to add the error code to the error set for the respective function.

Source

  pub inline fn fchmodat(dirfd: fd_t, path: []const u8, mode: mode_t, flags: u32) FChmodAtError!void {
    if (!fs.has_executable_bit) @compileError("fchmodat unsupported by target OS");

    // No special handling for linux is needed if we can use the libc fallback
    // or `flags` is empty. Glibc only added the fallback in 2.32.
    const skip_fchmodat_fallback = native_os != .linux or
        std.c.versionCheck(.{ .major = 2, .minor = 32, .patch = 0 }) or
        flags == 0;

    // This function is marked inline so that when flags is comptime-known,
    // skip_fchmodat_fallback will be comptime-known true.
    if (skip_fchmodat_fallback)
        return fchmodat1(dirfd, path, mode, flags);

    return fchmodat2(dirfd, path, mode, flags);
}  