1MKDIR(3P) POSIX Programmer's Manual MKDIR(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 mkdir, mkdirat — make a directory
13
15 #include <sys/stat.h>
16 int mkdir(const char *path, mode_t mode);
18 #include <fcntl.h>
20 int mkdirat(int fd, const char *path, mode_t mode);
22
24 The mkdir() function shall create a new directory with name path. The
25 file permission bits of the new directory shall be initialized from
26 mode. These file permission bits of the mode argument shall be modi‐
27 fied by the process' file creation mask.
28 When bits in mode other than the file permission bits are set, the
30 meaning of these additional bits is implementation-defined.
31 The directory's user ID shall be set to the process' effective user ID.
33 The directory's group ID shall be set to the group ID of the parent
34 directory or to the effective group ID of the process. Implementations
35 shall provide a way to initialize the directory's group ID to the group
36 ID of the parent directory. Implementations may, but need not, provide
37 an implementation-defined way to initialize the directory's group ID to
38 the effective group ID of the calling process.
39 The newly created directory shall be an empty directory.
41 If path names a symbolic link, mkdir() shall fail and set errno to
43 [EEXIST].
44 Upon successful completion, mkdir() shall mark for update the last data
46 access, last data modification, and last file status change timestamps
47 of the directory. Also, the last data modification and last file status
48 change timestamps of the directory that contains the new entry shall be
49 marked for update.
50 The mkdirat() function shall be equivalent to the mkdir() function
52 except in the case where path specifies a relative path. In this case
53 the newly created directory is created relative to the directory asso‐
54 ciated with the file descriptor fd instead of the current working
55 directory. If the access mode of the open file description associated
56 with the file descriptor is not O_SEARCH, the function shall check
57 whether directory searches are permitted using the current permissions
58 of the directory underlying the file descriptor. If the access mode is
59 O_SEARCH, the function shall not perform the check.
60 If mkdirat() is passed the special value AT_FDCWD in the fd parameter,
62 the current working directory shall be used and the behavior shall be
63 identical to a call to mkdir().
64
66 Upon successful completion, these functions shall return 0. Otherwise,
67 these functions shall return -1 and set errno to indicate the error. If
68 -1 is returned, no directory shall be created.
69
71 These functions shall fail if:
72 EACCES Search permission is denied on a component of the path prefix,
74 or write permission is denied on the parent directory of the
75 directory to be created.
76 EEXIST The named file exists.
78 ELOOP A loop exists in symbolic links encountered during resolution of
80 the path argument.
81 EMLINK The link count of the parent directory would exceed {LINK_MAX}.
83 ENAMETOOLONG
85 The length of a component of a pathname is longer than
86 {NAME_MAX}.
87 ENOENT A component of the path prefix specified by path does not name
89 an existing directory or path is an empty string.
90 ENOSPC The file system does not contain enough space to hold the con‐
92 tents of the new directory or to extend the parent directory of
93 the new directory.
94 ENOTDIR
96 A component of the path prefix names an existing file that is
97 neither a directory nor a symbolic link to a directory.
98 EROFS The parent directory resides on a read-only file system.
100 In addition, the mkdirat() function shall fail if:
102 EACCES The access mode of the open file description associated with fd
104 is not O_SEARCH and the permissions of the directory underlying
105 fd do not permit directory searches.
106 EBADF The path argument does not specify an absolute path and the fd
108 argument is neither AT_FDCWD nor a valid file descriptor open
109 for reading or searching.
110 ENOTDIR
112 The path argument is not an absolute path and fd is a file
113 descriptor associated with a non-directory file.
114 These functions may fail if:
116 ELOOP More than {SYMLOOP_MAX} symbolic links were encountered during
118 resolution of the path argument.
119 ENAMETOOLONG
121 The length of a pathname exceeds {PATH_MAX}, or pathname resolu‐
122 tion of a symbolic link produced an intermediate result with a
123 length that exceeds {PATH_MAX}.
124 The following sections are informative.
126
128 Creating a Directory
129 The following example shows how to create a directory named
130 /home/cnd/mod1, with read/write/search permissions for owner and group,
131 and with read/search permissions for others.
132 #include <sys/types.h>
135 #include <sys/stat.h>
136 int status;
138 ...
139 status = mkdir("/home/cnd/mod1", S_IRWXU | S_IRWXG | S_IROTH | S_IXOTH);
140
142 None.
143
145 The mkdir() function originated in 4.2 BSD and was added to System V in
146 Release 3.0.
147 4.3 BSD detects [ENAMETOOLONG].
149 The POSIX.1‐1990 standard required that the group ID of a newly created
151 directory be set to the group ID of its parent directory or to the
152 effective group ID of the creating process. FIPS 151‐2 required that
153 implementations provide a way to have the group ID be set to the group
154 ID of the containing directory, but did not prohibit implementations
155 also supporting a way to set the group ID to the effective group ID of
156 the creating process. Conforming applications should not assume which
157 group ID will be used. If it matters, an application can use chown() to
158 set the group ID after the directory is created, or determine under
159 what conditions the implementation will set the desired group ID.
160 The purpose of the mkdirat() function is to create a directory in
162 directories other than the current working directory without exposure
163 to race conditions. Any part of the path of a file could be changed in
164 parallel to the call to mkdir(), resulting in unspecified behavior. By
165 opening a file descriptor for the target directory and using the mkdi‐
166 rat() function it can be guaranteed that the newly created directory is
167 located relative to the desired directory.
168
170 None.
171
173 chmod(), mkdtemp(), mknod(), umask()
174 The Base Definitions volume of POSIX.1‐2017, <fcntl.h>, <sys_stat.h>,
176 <sys_types.h>
177
179 Portions of this text are reprinted and reproduced in electronic form
180 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
181 table Operating System Interface (POSIX), The Open Group Base Specifi‐
182 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
183 Electrical and Electronics Engineers, Inc and The Open Group. In the
184 event of any discrepancy between this version and the original IEEE and
185 The Open Group Standard, the original IEEE and The Open Group Standard
186 is the referee document. The original Standard can be obtained online
187 at http://www.opengroup.org/unix/online.html .
188 Any typographical or formatting errors that appear in this page are
190 most likely to have been introduced during the conversion of the source
191 files to man page format. To report such errors, see https://www.ker‐
192 nel.org/doc/man-pages/reporting_bugs.html .
193IEEE/The Open Group 2017 MKDIR(3P)