| .\" This manpage is Copyright (C) 1992 Drew Eckhardt; |
| .\" and Copyright (C) 1993 Michael Haardt |
| .\" and Copyright (C) 1993,1994 Ian Jackson |
| .\" and Copyright (C) 2006, 2014 Michael Kerrisk |
| .\" |
| .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) |
| .\" You may distribute it under the terms of the GNU General |
| .\" Public License. It comes with NO WARRANTY. |
| .\" %%%LICENSE_END |
| .\" |
| .TH MKDIR 2 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| mkdir, mkdirat \- create a directory |
| .SH SYNOPSIS |
| .nf |
| .B #include <sys/stat.h> |
| .\" .B #include <unistd.h> |
| .PP |
| .BI "int mkdir(const char *" pathname ", mode_t " mode ); |
| .PP |
| .BR "#include <fcntl.h> " "/* Definition of AT_* constants */" |
| .B #include <sys/stat.h> |
| .PP |
| .BI "int mkdirat(int " dirfd ", const char *" pathname ", mode_t " mode ); |
| .fi |
| .PP |
| .RS -4 |
| Feature Test Macro Requirements for glibc (see |
| .BR feature_test_macros (7)): |
| .RE |
| .PP |
| .BR mkdirat (): |
| .nf |
| Since glibc 2.10: |
| _POSIX_C_SOURCE >= 200809L |
| Before glibc 2.10: |
| _ATFILE_SOURCE |
| .fi |
| .SH DESCRIPTION |
| .BR mkdir () |
| attempts to create a directory named |
| .IR pathname . |
| .PP |
| The argument |
| .I mode |
| specifies the mode for the new directory (see |
| .BR inode (7)). |
| It is modified by the process's |
| .I umask |
| in the usual way: in the absence of a default ACL, the mode of the |
| created directory is |
| .RI ( mode " & \(ti" umask " & 0777)." |
| Whether other |
| .I mode |
| bits are honored for the created directory depends on the operating system. |
| For Linux, see NOTES below. |
| .PP |
| The newly created directory will be owned by the effective user ID of the |
| process. |
| If the directory containing the file has the set-group-ID |
| bit set, or if the filesystem is mounted with BSD group semantics |
| .RI ( "mount \-o bsdgroups" |
| or, synonymously |
| .IR "mount \-o grpid" ), |
| the new directory will inherit the group ownership from its parent; |
| otherwise it will be owned by the effective group ID of the process. |
| .PP |
| If the parent directory has the set-group-ID bit set, then so will the |
| newly created directory. |
| .\" |
| .\" |
| .SS mkdirat() |
| The |
| .BR mkdirat () |
| system call operates in exactly the same way as |
| .BR mkdir (), |
| except for the differences described here. |
| .PP |
| If the pathname given in |
| .I pathname |
| is relative, then it is interpreted relative to the directory |
| referred to by the file descriptor |
| .I dirfd |
| (rather than relative to the current working directory of |
| the calling process, as is done by |
| .BR mkdir () |
| for a relative pathname). |
| .PP |
| If |
| .I pathname |
| is relative and |
| .I dirfd |
| is the special value |
| .BR AT_FDCWD , |
| then |
| .I pathname |
| is interpreted relative to the current working |
| directory of the calling process (like |
| .BR mkdir ()). |
| .PP |
| If |
| .I pathname |
| is absolute, then |
| .I dirfd |
| is ignored. |
| .PP |
| See |
| .BR openat (2) |
| for an explanation of the need for |
| .BR mkdirat (). |
| .SH RETURN VALUE |
| .BR mkdir () |
| and |
| .BR mkdirat () |
| return zero on success. |
| On error, \-1 is returned and |
| .I errno |
| is set to indicate the error. |
| .SH ERRORS |
| .TP |
| .B EACCES |
| The parent directory does not allow write permission to the process, |
| or one of the directories in |
| .I pathname |
| did not allow search permission. |
| (See also |
| .BR path_resolution (7).) |
| .TP |
| .B EDQUOT |
| The user's quota of disk blocks or inodes on the filesystem has been |
| exhausted. |
| .TP |
| .B EEXIST |
| .I pathname |
| already exists (not necessarily as a directory). |
| This includes the case where |
| .I pathname |
| is a symbolic link, dangling or not. |
| .TP |
| .B EFAULT |
| .IR pathname " points outside your accessible address space." |
| .TP |
| .B EINVAL |
| The final component ("basename") of the new directory's |
| .I pathname |
| is invalid |
| (e.g., it contains characters not permitted by the underlying filesystem). |
| .TP |
| .B ELOOP |
| Too many symbolic links were encountered in resolving |
| .IR pathname . |
| .TP |
| .B EMLINK |
| The number of links to the parent directory would exceed |
| .BR LINK_MAX . |
| .TP |
| .B ENAMETOOLONG |
| .IR pathname " was too long." |
| .TP |
| .B ENOENT |
| A directory component in |
| .I pathname |
| does not exist or is a dangling symbolic link. |
| .TP |
| .B ENOMEM |
| Insufficient kernel memory was available. |
| .TP |
| .B ENOSPC |
| The device containing |
| .I pathname |
| has no room for the new directory. |
| .TP |
| .B ENOSPC |
| The new directory cannot be created because the user's disk quota is |
| exhausted. |
| .TP |
| .B ENOTDIR |
| A component used as a directory in |
| .I pathname |
| is not, in fact, a directory. |
| .TP |
| .B EPERM |
| The filesystem containing |
| .I pathname |
| does not support the creation of directories. |
| .TP |
| .B EROFS |
| .I pathname |
| refers to a file on a read-only filesystem. |
| .PP |
| The following additional errors can occur for |
| .BR mkdirat (): |
| .TP |
| .B EBADF |
| .I dirfd |
| is not a valid file descriptor. |
| .TP |
| .B ENOTDIR |
| .I pathname |
| is relative and |
| .I dirfd |
| is a file descriptor referring to a file other than a directory. |
| .SH VERSIONS |
| .BR mkdirat () |
| was added to Linux in kernel 2.6.16; |
| library support was added to glibc in version 2.4. |
| .SH CONFORMING TO |
| .BR mkdir (): |
| SVr4, BSD, POSIX.1-2001, POSIX.1-2008. |
| .\" SVr4 documents additional EIO, EMULTIHOP |
| .PP |
| .BR mkdirat (): |
| POSIX.1-2008. |
| .SH NOTES |
| Under Linux, apart from the permission bits, the |
| .B S_ISVTX |
| .I mode |
| bit is also honored. |
| .PP |
| There are many infelicities in the protocol underlying NFS. |
| Some of these affect |
| .BR mkdir (). |
| .SS Glibc notes |
| On older kernels where |
| .BR mkdirat () |
| is unavailable, the glibc wrapper function falls back to the use of |
| .BR mkdir (). |
| When |
| .I pathname |
| is a relative pathname, |
| glibc constructs a pathname based on the symbolic link in |
| .IR /proc/self/fd |
| that corresponds to the |
| .IR dirfd |
| argument. |
| .SH SEE ALSO |
| .BR mkdir (1), |
| .BR chmod (2), |
| .BR chown (2), |
| .BR mknod (2), |
| .BR mount (2), |
| .BR rmdir (2), |
| .BR stat (2), |
| .BR umask (2), |
| .BR unlink (2), |
| .BR acl (5), |
| .BR path_resolution (7) |