man2/mkdir.2

   1 .\" This manpage is Copyright (C) 1992 Drew Eckhardt;
   2 .\"             and Copyright (C) 1993 Michael Haardt
   3 .\"             and Copyright (C) 1993,1994 Ian Jackson
   4 .\"             and Copyright (C) 2006, 2014 Michael Kerrisk
   5 .\"
   6 .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
   7 .\" You may distribute it under the terms of the GNU General
   8 .\" Public License. It comes with NO WARRANTY.
   9 .\" %%%LICENSE_END
  10 .\"
  11 .TH MKDIR 2 2017-09-15 "Linux" "Linux Programmer's Manual"
  12 .SH NAME
  13 mkdir, mkdirat \- create a directory
  14 .SH SYNOPSIS
  15 .nf
  16 .B #include <sys/stat.h>
  17 .B #include <sys/types.h>
  18 .\" .B #include <unistd.h>
  19 .PP
  20 .BI "int mkdir(const char *" pathname ", mode_t " mode );
  21
  22 .BR "#include <fcntl.h>           " "/* Definition of AT_* constants */"
  23 .B #include <sys/stat.h>
  24 .PP
  25 .BI "int mkdirat(int " dirfd ", const char *" pathname ", mode_t " mode );
  26 .fi
  27 .PP
  28 .in -4n
  29 Feature Test Macro Requirements for glibc (see
  30 .BR feature_test_macros (7)):
  31 .in
  32 .PP
  33 .BR mkdirat ():
  34 .PD 0
  35 .ad l
  36 .RS 4
  37 .TP 4
  38 Since glibc 2.10:
  39 _POSIX_C_SOURCE\ >=\ 200809L
  40 .TP
  41 Before glibc 2.10:
  42 _ATFILE_SOURCE
  43 .RE
  44 .ad
  45 .PD
  46 .SH DESCRIPTION
  47 .BR mkdir ()
  48 attempts to create a directory named
  49 .IR pathname .
  50 .PP
  51 The argument
  52 .I mode
  53 specifies the mode for the new directory (see
  54 .BR inode (7)).
  55 It is modified by the process's
  56 .I umask
  57 in the usual way: in the absence of a default ACL, the mode of the
  58 created directory is
  59 .RI ( mode " & ~" umask " & 0777)."
  60 Whether other
  61 .I mode
  62 bits are honored for the created directory depends on the operating system.
  63 For Linux, see NOTES below.
  64 .PP
  65 The newly created directory will be owned by the effective user ID of the
  66 process.
  67 If the directory containing the file has the set-group-ID
  68 bit set, or if the filesystem is mounted with BSD group semantics
  69 .RI ( "mount -o bsdgroups"
  70 or, synonymously
  71 .IR "mount -o grpid" ),
  72 the new directory will inherit the group ownership from its parent;
  73 otherwise it will be owned by the effective group ID of the process.
  74 .PP
  75 If the parent directory has the set-group-ID bit set, then so will the
  76 newly created directory.
  77 .\"
  78 .\"
  79 .SS mkdirat()
  80 The
  81 .BR mkdirat ()
  82 system call operates in exactly the same way as
  83 .BR mkdir (),
  84 except for the differences described here.
  85 .PP
  86 If the pathname given in
  87 .I pathname
  88 is relative, then it is interpreted relative to the directory
  89 referred to by the file descriptor
  90 .I dirfd
  91 (rather than relative to the current working directory of
  92 the calling process, as is done by
  93 .BR mkdir ()
  94 for a relative pathname).
  95 .PP
  96 If
  97 .I pathname
  98 is relative and
  99 .I dirfd
 100 is the special value
 101 .BR AT_FDCWD ,
 102 then
 103 .I pathname
 104 is interpreted relative to the current working
 105 directory of the calling process (like
 106 .BR mkdir ()).
 107 .PP
 108 If
 109 .I pathname
 110 is absolute, then
 111 .I dirfd
 112 is ignored.
 113 .PP
 114 See
 115 .BR openat (2)
 116 for an explanation of the need for
 117 .BR mkdirat ().
 118 .SH RETURN VALUE
 119 .BR mkdir ()
 120 and
 121 .BR mkdirat ()
 122 return zero on success, or \-1 if an error occurred (in which case,
 123 .I errno
 124 is set appropriately).
 125 .SH ERRORS
 126 .TP
 127 .B EACCES
 128 The parent directory does not allow write permission to the process,
 129 or one of the directories in
 130 .I pathname
 131 did not allow search permission.
 132 (See also
 133 .BR path_resolution (7).)
 134 .TP
 135 .B EDQUOT
 136 The user's quota of disk blocks or inodes on the filesystem has been
 137 exhausted.
 138 .TP
 139 .B EEXIST
 140 .I pathname
 141 already exists (not necessarily as a directory).
 142 This includes the case where
 143 .I pathname
 144 is a symbolic link, dangling or not.
 145 .TP
 146 .B EFAULT
 147 .IR pathname " points outside your accessible address space."
 148 .TP
 149 .B EINVAL
 150 The final component ("basename") of the new directory's
 151 .I pathname
 152 is invalid
 153 (e.g., it contains characters not permitted by the underlying filesystem).
 154 .TP
 155 .B ELOOP
 156 Too many symbolic links were encountered in resolving
 157 .IR pathname .
 158 .TP
 159 .B EMLINK
 160 The number of links to the parent directory would exceed
 161 .BR LINK_MAX .
 162 .TP
 163 .B ENAMETOOLONG
 164 .IR pathname " was too long."
 165 .TP
 166 .B ENOENT
 167 A directory component in
 168 .I pathname
 169 does not exist or is a dangling symbolic link.
 170 .TP
 171 .B ENOMEM
 172 Insufficient kernel memory was available.
 173 .TP
 174 .B ENOSPC
 175 The device containing
 176 .I pathname
 177 has no room for the new directory.
 178 .TP
 179 .B ENOSPC
 180 The new directory cannot be created because the user's disk quota is
 181 exhausted.
 182 .TP
 183 .B ENOTDIR
 184 A component used as a directory in
 185 .I pathname
 186 is not, in fact, a directory.
 187 .TP
 188 .B EPERM
 189 The filesystem containing
 190 .I pathname
 191 does not support the creation of directories.
 192 .TP
 193 .B EROFS
 194 .I pathname
 195 refers to a file on a read-only filesystem.
 196 .PP
 197 The following additional errors can occur for
 198 .BR mkdirat ():
 199 .TP
 200 .B EBADF
 201 .I dirfd
 202 is not a valid file descriptor.
 203 .TP
 204 .B ENOTDIR
 205 .I pathname
 206 is relative and
 207 .I dirfd
 208 is a file descriptor referring to a file other than a directory.
 209 .SH VERSIONS
 210 .BR mkdirat ()
 211 was added to Linux in kernel 2.6.16;
 212 library support was added to glibc in version 2.4.
 213 .SH CONFORMING TO
 214 .BR mkdir ():
 215 SVr4, BSD, POSIX.1-2001, POSIX.1-2008.
 216 .\" SVr4 documents additional EIO, EMULTIHOP
 217 .PP
 218 .BR mkdirat ():
 219 POSIX.1-2008.
 220 .SH NOTES
 221 Under Linux, apart from the permission bits, the
 222 .B S_ISVTX
 223 .I mode
 224 bit is also honored.
 225 .PP
 226 There are many infelicities in the protocol underlying NFS.
 227 Some of these affect
 228 .BR mkdir ().
 229 .SS Glibc notes
 230 On older kernels where
 231 .BR mkdirat ()
 232 is unavailable, the glibc wrapper function falls back to the use of
 233 .BR mkdir ().
 234 When
 235 .I pathname
 236 is a relative pathname,
 237 glibc constructs a pathname based on the symbolic link in
 238 .IR /proc/self/fd
 239 that corresponds to the
 240 .IR dirfd
 241 argument.
 242 .SH SEE ALSO
 243 .BR mkdir (1),
 244 .BR chmod (2),
 245 .BR chown (2),
 246 .BR mknod (2),
 247 .BR mount (2),
 248 .BR rmdir (2),
 249 .BR stat (2),
 250 .BR umask (2),
 251 .BR unlink (2),
 252 .BR acl (5)
 253 .BR path_resolution (7)