.Dt MKDIR 2
.Os BSD 4.2
.Sh NAME
-.Nm mkdir
+.Nm mkdir ,
+.Nm mkdirat
.Nd make a directory file
.Sh SYNOPSIS
-.Fd #include <sys/types.h>
.Fd #include <sys/stat.h>
.Ft int
-.Fn mkdir "const char *path" "mode_t mode"
+.Fo mkdir
+.Fa "const char *path"
+.Fa "mode_t mode"
+.Fc
+.Ft int
+.Fn mkdirat "int fd" "const char *path" "mode_t mode"
.Sh DESCRIPTION
The directory
.Fa path
.Fa mode
and restricted by the
.Xr umask 2
-of the calling process.
+of the calling process. See
+.Xr chmod 2
+for the possible permission bit masks for
+.Fa mode .
.Pp
The directory's owner ID is set to the process's effective user ID.
The directory's group ID is set to that of the parent directory in
which it is created.
+.Pp
+Note: the behavior of
+.Fn mkdir
+is undefined when mode bits other than the low 9 bits are used. Use
+.Xr chmod 2
+after
+.Fn mkdir
+to explicitly set the other bits (See example below).
+.Pp
+The
+.Fn mkdirat
+system call is equivalent to
+.Fn mkdir
+except in the case where
+.Fa path
+specifies a relative path.
+In this case the newly created directory is created relative to the
+directory associated with the file descriptor
+.Fa fd
+instead of the current working directory.
+If
+.Fn mkdirat
+is passed the special value
+.Dv AT_FDCWD
+in the
+.Fa fd
+parameter, the current working directory is used and the behavior is
+identical to a call to
+.Fn mkdir .
.Sh RETURN VALUES
A 0 return value indicates success. A -1 return value
indicates an error, and an error code is stored in
.Va errno .
.Sh ERRORS
-.Fn Mkdir
+.Fn mkdir
will fail and no directory will be created if:
.Bl -tag -width Er
-.It Bq Er ENOTDIR
-A component of the path prefix is not a directory.
-.It Bq Er ENAMETOOLONG
-A component of a pathname exceeded
-.Dv {NAME_MAX}
-characters, or an entire path name exceeded
-.Dv {PATH_MAX}
-characters.
-.It Bq Er ENOENT
-A component of the path prefix does not exist.
+.\" ==========
.It Bq Er EACCES
Search permission is denied for a component of the path prefix.
-.It Bq Er ELOOP
-Too many symbolic links were encountered in translating the pathname.
-.It Bq Er EROFS
-The named file resides on a read-only file system.
-.It Bq Er EEXIST
-The named file exists.
-.It Bq Er ENOSPC
-The new directory cannot be created because there is no space left
-on the file system that will contain the directory.
-.It Bq Er ENOSPC
-There are no free inodes on the file system on which the
-directory is being created.
+.\" ==========
+.It Bq Er EACCES
+Write permission is denied for the parent directory.
+.\" ==========
.It Bq Er EDQUOT
The new directory cannot be created because the user's
quota of disk blocks on the file system that will
contain the directory has been exhausted.
+.\" ==========
.It Bq Er EDQUOT
The user's quota of inodes on the file system on
which the directory is being created has been exhausted.
-.It Bq Er EIO
-An I/O error occurred while making the directory entry or allocating the inode.
-.It Bq Er EIO
-An I/O error occurred while reading from or writing to the file system.
+.\" ==========
+.It Bq Er EEXIST
+The named file exists.
+.\" ==========
.It Bq Er EFAULT
.Fa Path
points outside the process's allocated address space.
+.\" ==========
+.It Bq Er EIO
+An I/O error occurred while making the directory entry
+or allocating the inode.
+.\" ==========
+.It Bq Er EIO
+An I/O error occurred while reading from or writing to the file system.
+.\" ==========
+.It Bq Er EISDIR
+The named file is the root directory.
+.\" ==========
+.It Bq Er ELOOP
+Too many symbolic links were encountered in translating the pathname.
+This is taken to be indicative of a looping symbolic link.
+.\" ==========
+.It Bq Er EMLINK
+The parent directory already has {LINK_MAX} links.
+.\" ==========
+.It Bq Er ENAMETOOLONG
+A component of a pathname exceeded
+.Dv {NAME_MAX}
+characters, or an entire path name exceeded
+.Dv {PATH_MAX}
+characters.
+.\" ==========
+.It Bq Er ENOENT
+A component of the path prefix does not exist
+or path is an empty string.
+.It Bq Er ENOSPC
+The new directory cannot be created because there is no space left
+on the file system that would contain it.
+.\" ==========
+.It Bq Er ENOSPC
+There are no free inodes on the file system on which the
+directory is being created.
+.\" ==========
+.It Bq Er ENOTDIR
+A component of the path prefix is not a directory.
+.\" ==========
+.It Bq Er EROFS
+The parent directory resides on a read-only file system.
+.El
+.Pp
+In addition to the errors returned by the
+.Fn mkdir ,
+the
+.Fn mkdirat
+function may fail if:
+.Bl -tag -width Er
+.It Bq Er EBADF
+The
+.Fa path
+argument does not specify an absolute path and the
+.Fa fd
+argument is neither
+.Dv AT_FDCWD
+nor a valid file descriptor open for searching.
+.It Bq Er ENOTDIR
+The
+.Fa path
+argument is not an absolute path and
+.Fa fd
+is neither
+.Dv AT_FDCWD
+nor a file descriptor associated with a directory.
.El
+.Sh EXAMPLE
+.Bd -literal -offset indent
+
+int main (int argc, const char * argv[])
+{
+ /* The behavior of mkdir is undefined for anything other than the "permission" bits */
+ if (mkdir("/tmp/blah", 0777))
+ perror("/tmp/blah");
+
+ /* So we need to set the sticky/executable bits explicitly with chmod after calling mkdir */
+ if (chmod("/tmp/blah", 07777))
+ perror("/tmp/blah");
+}
+
+.Ed
+.Sh LEGACY SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <sys/stat.h>
+.Pp
+The include file
+.In sys/types.h
+is necessary.
.Sh SEE ALSO
.Xr chmod 2 ,
.Xr stat 2 ,
-.Xr umask 2
+.Xr umask 2 ,
+.Xr compat 5
.Sh STANDARDS
The
.Fn mkdir
function conforms to
.St -p1003.1-88 .
+The
+.Fn mkdirat
+system call is expected to conform to POSIX.1-2008 .
+.Sh HISTORY
+The
+.Fn mkdirat
+system call appeared in OS X 10.10
projects / apple / xnu.git / blobdiff