mkdirat

mkdirat is a POSIX-compliant system call that creates a new directory with a pathname relative to a directory file descriptor. If the dirfd argument refers to AT_FDCWD, the pathname is interpreted relative to the process’s current working directory. If pathname is absolute, dirfd is ignored. This design enables creating directories within an already opened directory and helps avoid certain race conditions that can occur when changing directories.

The function prototype is int mkdirat(int dirfd, const char *pathname, mode_t mode). The mode specifies the permissions for the newly created directory and is further modified by the process’s umask. On success, mkdirat returns 0. On failure, it returns -1 and sets errno to indicate the error.

Behavior and restrictions: mkdirat creates the directory as a child of the directory described by dirfd. If the target pathname already exists, the call fails with EEXIST. If the directory or its parent cannot be searched due to insufficient permissions, errors such as EACCES or ENOTDIR may be returned. If pathname is relative, it is resolved relative to the directory file descriptor; if absolute, dirfd is ignored. The exact set of possible error codes includes common filesystem-related errors such as ENOENT, EINVAL, EPERM, and others, depending on the filesystem and platform.

Compatibility and usage: mkdirat is widely supported on Linux, BSD variants, and macOS, and forms part of the POSIX.1-2008 and later specifications. It is commonly used in conjunction with open, openat, and related functions to perform safe, race-condition-resistant file and directory operations within an already opened directory.

See also: mkdir, openat, mkdirat on other platforms, fstatat.