--- name: "mkdirat" section: "2" platform: "macos" package: "xnu" version: "12377.121.6" release: "macOS 26.5" platforms: ["linux", "freebsd", "macos"] url: "https://new.carta.tech/mkdir/2" --- # mkdirat(2) make a directory file Part of [mkdir(2)](/mkdir/2.md). ## NAME **mkdir**, **mkdirat** – make a directory file ## SYNOPSIS **#include \** *int*\ **mkdir**(*const char \*path*, *mode\_t mode*); *int*\ **mkdirat**(*int fd*, *const char \*path*, *mode\_t mode*); ## DESCRIPTION The directory *path* is created with the access permissions specified by *mode* and restricted by the [umask(2)](/umask/2.md) of the calling process. See [chmod(2)](/chmod/2.md) for the possible permission bit masks for *mode*. The directory's owner ID is set to the process's effective user ID. The directory's group ID is set to that of the parent directory in which it is created. Note: the behavior of **mkdir**() is undefined when mode bits other than the low 9 bits are used. Use [chmod(2)](/chmod/2.md) after **mkdir**() to explicitly set the other bits (See example below). The **mkdirat**() system call is equivalent to **mkdir**() except in the case where *path* specifies a relative path. In this case the newly created directory is created relative to the directory associated with the file descriptor *fd* instead of the current working directory. If **mkdirat**() is passed the special value AT\_FDCWD in the *fd* parameter, the current working directory is used and the behavior is identical to a call to **mkdir**(). ## RETURN VALUES A 0 return value indicates success. A -1 return value indicates an error, and an error code is stored in *errno*. ## ERRORS **mkdir**() will fail and no directory will be created if: - \[EACCES\] Search permission is denied for a component of the path prefix. - \[EACCES\] Write permission is denied for the parent directory. - \[EDQUOT\] The new directory cannot be created because the user's quota of disk blocks on the file system that will contain the directory has been exhausted. - \[EDQUOT\] The user's quota of inodes on the file system on which the directory is being created has been exhausted. - \[EEXIST\] The named file exists. - \[EFAULT\] *Path* points outside the process's allocated address space. - \[EIO\] An I/O error occurred while making the directory entry or allocating the inode. - \[EIO\] An I/O error occurred while reading from or writing to the file system. - \[EISDIR\] The named file is the root directory. - \[ELOOP\] Too many symbolic links were encountered in translating the pathname. This is taken to be indicative of a looping symbolic link. - \[EMLINK\] The parent directory already has {LINK\_MAX} links. - \[ENAMETOOLONG\] A component of a pathname exceeded {NAME\_MAX} characters, or an entire path name exceeded {PATH\_MAX} characters. - \[ENOENT\] A component of the path prefix does not exist or path is an empty string. - \[ENOSPC\] The new directory cannot be created because there is no space left on the file system that would contain it. - \[ENOSPC\] There are no free inodes on the file system on which the directory is being created. - \[ENOTDIR\] A component of the path prefix is not a directory. - \[EROFS\] The parent directory resides on a read-only file system. In addition to the errors returned by the **mkdir**(), the **mkdirat**() function may fail if: - \[EBADF\] The *path* argument does not specify an absolute path and the *fd* argument is neither AT\_FDCWD nor a valid file descriptor open for searching. - \[ENOTDIR\] The *path* argument is not an absolute path and *fd* is neither AT\_FDCWD nor a file descriptor associated with a directory. - \[EILSEQ\] The filename does not match the encoding rules. ## EXAMPLE ``` int main (int argc, const char * argv[]) { /* The behavior of mkdir is undefined for anything other than the "permission" bits */ if (mkdir("/tmp/blah", 0777)) perror("/tmp/blah"); /* So we need to set the sticky/executable bits explicitly with chmod after calling mkdir */ if (chmod("/tmp/blah", 07777)) perror("/tmp/blah"); } ``` ## LEGACY SYNOPSIS **#include \** **#include \** The include file ⟨sys/types.h⟩ is necessary. ## SEE ALSO [chmod(2)](/chmod/2.md), [stat(2)](/stat/2.md), [umask(2)](/umask/2.md), [compat(5)](/compat/5.md) ## STANDARDS The **mkdir**() function conforms to IEEE Std 1003.1-1988 (“POSIX.1”). The **mkdirat**() system call is expected to conform to POSIX.1-2008 . ## HISTORY The **mkdirat**() system call appeared in OS X 10.10