mkdir or mkdirat Subroutine

Edit online

Purpose

Creates a directory.

Library

Standard C Library (libc.a)

Syntax

#include <sys/stat.h>
int mkdir (Path,  Mode)
const char *Path;
mode_t Mode;

int mkdirat (DirFileDescriptor, Path, Mode)
int DirFileDescriptor;
const char * Path;
mode_t Mode;

Description

The mkdir and mkdirat subroutines create a new directory.

The new directory has the following:

  • The owner ID is set to the process-effective user ID.
  • If the parent directory has the SetFileGroupID (S_ISGID) attribute set, the new directory inherits the group ID of the parent directory. Otherwise, the group ID of the new directory is set to the effective group ID of the calling process.
  • Permission and attribute bits are set according to the value of the Mode parameter, with the following modifications:
    • All bits set in the process-file mode-creation mask are cleared.
    • The SetFileUserID and Sticky (S_ISVTX) attributes are cleared.
  • If the Path variable names a symbolic link, the link is followed. The new directory is created where the variable pointed.

The mkdirat subroutine is equivalent to the mkdir subroutine if the DirFileDescriptor parameter is set to AT_FDCWD or the Path parameter is an absolute path name. If the DirFileDescriptor parameter is a valid file descriptor of an open directory and the Path parameter is a relative path name, the Path parameter is considered as the relative path to the directory that is associated with the DirFileDescriptor parameter instead of the current working directory.

If the DirFileDescriptor parameter is opened without the O_SEARCH open flag, the subroutine checks to determine whether directory searches are permitted for that directory by using the current permissions of the directory. If the directory is opened with the O_SEARCH open flag, the subroutine does not perform the check for that directory.

Parameters

Item Description
Path Specifies the name of the new directory. If Network File System (NFS) is installed on your system, this path can cross into another node. In this case, the new directory is created at that node.

To execute the mkdir or mkdirat subroutine successfully, a process must have write permission to the parent directory of the Path parameter.
Mode Specifies the mask for the read, write, and execute flags for owner, group, and others. The Mode parameter specifies directory permissions and attributes. This parameter is constructed by logically ORing values described in the <sys/mode.h> file.
DirFileDescriptor Specifies the file descriptor of an open directory.

Return Values

Upon successful completion, the mkdir and mkdirat subroutines return a value of 0. Otherwise, a value of -1 is returned, and the errno global variable is set to indicate the error.

Error Codes

The mkdir and mkdirat subroutines are unsuccessful and the directory is not created if one or more of the following are true:

Item Description
EACCES Creating the requested directory requires writing in a directory with a mode that denies write permission.
EEXIST The named file already exists.
EROFS The named file resides on a read-only file system.
ENOSPC The file system does not contain enough space to hold the contents of the new directory or to extend the parent directory of the new directory.
EMLINK The link count of the parent directory exceeds the maximum (LINK_MAX) number. (LINK_MAX) is defined in limits.h file.
ENAMETOOLONG The Path parameter or a path component is too long and cannot be truncated.
ENOENT A component of the path prefix does not exist or the Path parameter points to an empty string.
ENOTDIR A component of the path prefix is not a directory.
EDQUOT The directory in which the entry for the new directory is being placed cannot be extended, or an i-node or disk blocks could not be allocated for the new directory because the user's or group's quota of disk blocks or i-nodes on the file system containing the directory is exhausted.

The mkdirat subroutine is unsuccessful if one or more of the following settings are true:

Item Description
EBADF The Path parameter does not specify an absolute path and the DirFileDescriptor parameter is neither AT_FDCWD nor a valid file descriptor.
ENOTDIR The Path parameter does not specify an absolute path and the DirFileDescriptor parameter is neither AT_FDCWD nor a file descriptor associated with a directory.

The mkdir and mkdirat subroutines can be unsuccessful for other reasons. See "Appendix A. Base Operating System Error Codes for Services That Require Path-Name Resolution" for a list of additional errors.

If NFS is installed on the system, the mkdir and mkdirat subroutines are also unsuccessful if the following is true:

Item Description
ETIMEDOUT The connection timed out.