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