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