mkdir(3p)

1MKDIR(P)                   POSIX Programmer's Manual                  MKDIR(P)
2
3
4

NAME

6       mkdir - make a directory
7

SYNOPSIS

9       #include <sys/stat.h>
10
11       int mkdir(const char *path, mode_t mode);
12
13

DESCRIPTION

15       The  mkdir()  function shall create a new directory with name path. The
16       file permission bits of the new directory  shall  be  initialized  from
17       mode. These file permission bits of the mode argument shall be modified
18       by the process' file creation mask.
19
20       When bits in mode other than the file  permission  bits  are  set,  the
21       meaning of these additional bits is implementation-defined.
22
23       The directory's user ID shall be set to the process' effective user ID.
24       The directory's group ID shall be set to the group  ID  of  the  parent
25       directory or to the effective group ID of the process.  Implementations
26       shall provide a way to initialize the directory's group ID to the group
27       ID  of the parent directory. Implementations may, but need not, provide
28       an implementation-defined way to initialize the directory's group ID to
29       the effective group ID of the calling process.
30
31       The newly created directory shall be an empty directory.
32
33       If  path  names  a  symbolic  link, mkdir() shall fail and set errno to
34       [EEXIST].
35
36       Upon successful completion, mkdir() shall mark for update the st_atime,
37       st_ctime,  and st_mtime fields of the directory. Also, the st_ctime and
38       st_mtime fields of the directory that contains the new entry  shall  be
39       marked for update.
40

RETURN VALUE

42       Upon successful completion, mkdir() shall return 0. Otherwise, -1 shall
43       be returned, no directory shall be created, and errno shall be  set  to
44       indicate the error.
45

ERRORS

47       The mkdir() function shall fail if:
48
49       EACCES Search  permission  is denied on a component of the path prefix,
50              or write permission is denied on the  parent  directory  of  the
51              directory to be created.
52
53       EEXIST The named file exists.
54
55       ELOOP  A loop exists in symbolic links encountered during resolution of
56              the path argument.
57
58       EMLINK The link count of the parent directory would exceed {LINK_MAX}.
59
60       ENAMETOOLONG
61              The length of the path argument exceeds {PATH_MAX} or a pathname
62              component is longer than {NAME_MAX}.
63
64       ENOENT A  component  of the path prefix specified by path does not name
65              an existing directory or path is an empty string.
66
67       ENOSPC The file system does not contain enough space to hold  the  con‐
68              tents  of the new directory or to extend the parent directory of
69              the new directory.
70
71       ENOTDIR
72              A component of the path prefix is not a directory.
73
74       EROFS  The parent directory resides on a read-only file system.
75
76
77       The mkdir() function may fail if:
78
79       ELOOP  More than {SYMLOOP_MAX} symbolic links were  encountered  during
80              resolution of the path argument.
81
82       ENAMETOOLONG
83              As a result of encountering a symbolic link in resolution of the
84              path argument, the length of  the  substituted  pathname  string
85              exceeded {PATH_MAX}.
86
87
88       The following sections are informative.
89

EXAMPLES

91   Creating a Directory
92       The   following   example   shows  how  to  create  a  directory  named
93       /home/cnd/mod1, with read/write/search permissions for owner and group,
94       and with read/search permissions for others.
95
96
97              #include <sys/types.h>
98              #include <sys/stat.h>
99
100
101              int status;
102              ...
103              status = mkdir("/home/cnd/mod1", S_IRWXU | S_IRWXG | S_IROTH | S_IXOTH);
104

APPLICATION USAGE

106       None.
107

RATIONALE

109       The mkdir() function originated in 4.2 BSD and was added to System V in
110       Release 3.0.
111
112       4.3 BSD detects [ENAMETOOLONG].
113
114       The POSIX.1-1990 standard required that the group ID of a newly created
115       directory  be  set  to  the  group ID of its parent directory or to the
116       effective group ID of the creating process. FIPS  151-2  required  that
117       implementations  provide a way to have the group ID be set to the group
118       ID of the containing directory, but did  not  prohibit  implementations
119       also  supporting a way to set the group ID to the effective group ID of
120       the creating process. Conforming applications should not  assume  which
121       group ID will be used. If it matters, an application can use chown() to
122       set the group ID after the directory is  created,  or  determine  under
123       what conditions the implementation will set the desired group ID.
124

FUTURE DIRECTIONS

126       None.
127

COPYRIGHT

133       Portions of this text are reprinted and reproduced in  electronic  form
134       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
135       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
136       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
137       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
138       event of any discrepancy between this version and the original IEEE and
139       The Open Group Standard, the original IEEE and The Open Group  Standard
140       is  the  referee document. The original Standard can be obtained online
141       at http://www.opengroup.org/unix/online.html .
142
143
144
145IEEE/The Open Group                  2003                             MKDIR(P)