'\" et

.TH MKDIR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual"

.SH PROLOG

This manual page is part of the POSIX Programmer's Manual.

The Linux implementation of this interface may differ (consult

the corresponding Linux manual page for details of Linux behavior),

or the interface may not be implemented on Linux.

.SH NAME

mkdir, mkdirat

\(em make a directory relative to directory file descriptor

.SH SYNOPSIS

.LP

.nf

#include <sys/stat.h>

.P

int mkdir(const char *\fIpath\fP, mode_t \fImode\fP);

int mkdirat(int \fIfd\fP, const char *\fIpath\fP, mode_t \fImode\fP);

.fi

.SH DESCRIPTION

The

\fImkdir\fR()

function shall create a new directory with name

.IR path .

The file permission bits of the new directory shall be initialized from

.IR mode .

These file permission bits of the

.IR mode

argument shall be modified by the process' file creation mask.

.P

When bits in

.IR mode

other than the file permission bits are set, the meaning of these

additional bits is implementation-defined.

.P

The directory's user ID shall be set to the process' effective user ID.

The directory's group ID shall be set to the group ID of the parent

directory or to the effective group ID of the process. Implementations

shall provide a way to initialize the directory's group ID to the group

ID of the parent directory. Implementations may, but need not, provide

an implementation-defined way to initialize the directory's group ID to

the effective group ID of the calling process.

.P

The newly created directory shall be an empty directory.

.P

If

.IR path

names a symbolic link,

\fImkdir\fR()

shall fail and set

.IR errno

to

.BR [EEXIST] .

.P

Upon successful completion,

\fImkdir\fR()

shall mark for update the last data access, last data modification,

and last file status change timestamps of the directory. Also, the last

data modification and last file status change timestamps of the directory

that contains the new entry shall be marked for update.

.P

The

\fImkdirat\fR()

function shall be equivalent to the

\fImkdir\fR()

function except in the case where

.IR path

specifies a relative path. In this case the newly created directory is

created relative to the directory associated with the file descriptor

.IR fd

instead of the current working directory. If the file descriptor was

opened without O_SEARCH, the function shall check whether directory

searches are permitted using the current permissions of the directory

underlying the file descriptor. If the file descriptor was opened with

O_SEARCH, the function shall not perform the check.

.P

If

\fImkdirat\fR()

is passed the special value AT_FDCWD in the

.IR fd

parameter, the current working directory shall be used and the behavior

shall be identical to a call to

\fImkdir\fR().

.SH "RETURN VALUE"

Upon successful completion, these functions shall return 0.

Otherwise, these functions shall return \(mi1 and set

.IR errno

to indicate the error. If \(mi1 is returned, no directory shall be created.

.SH ERRORS

These functions shall fail if:

.TP

.BR EACCES

Search permission is denied on a component of the path prefix, or write

permission is denied on the parent directory of the directory to be

created.

.TP

.BR EEXIST

The named file exists.

.TP

.BR ELOOP

A loop exists in symbolic links encountered during resolution of the

.IR path

argument.

.TP

.BR EMLINK

The link count of the parent directory would exceed

{LINK_MAX}.

.TP

.BR ENAMETOOLONG

.br

The length of a component of a pathname is longer than

{NAME_MAX}.

.TP

.BR ENOENT

A component of the path prefix specified by

.IR path

does not name an existing directory or

.IR path

is an empty string.

.TP

.BR 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.

.TP

.BR ENOTDIR

A component of the path prefix names an existing file that is neither

a directory nor a symbolic link to a directory.

.TP

.BR EROFS

The parent directory resides on a read-only file system.

.P

In addition, the

\fImkdirat\fR()

function shall fail if:

.TP

.BR EBADF

The

.IR path

argument does not specify an absolute path and the

.IR fd

argument is neither AT_FDCWD nor a valid file descriptor open for reading

or searching.

.TP

.BR ENOTDIR

The

.IR path

argument is not an absolute path and

.IR fd

is a file descriptor associated with a non-directory file.

.P

These functions may fail if:

.TP

.BR ELOOP

More than

{SYMLOOP_MAX}

symbolic links were encountered during resolution of the

.IR path

argument.

.TP

.BR ENAMETOOLONG

.br

The length of a pathname exceeds

{PATH_MAX},

or pathname resolution of a symbolic link produced an intermediate

result with a length that exceeds

{PATH_MAX}.

.LP

.IR "The following sections are informative."

.SH EXAMPLES

.SS "Creating a Directory"

.P

The following example shows how to create a directory named

.BR /home/cnd/mod1 ,

with read/write/search permissions for owner and group, and with

read/search permissions for others.

.sp

.RS 4

.nf

\fB

#include <sys/types.h>

#include <sys/stat.h>

.P

int status;

\&...

status = mkdir("/home/cnd/mod1", S_IRWXU | S_IRWXG | S_IROTH | S_IXOTH);

.fi \fR

.P

.RE

.SH "APPLICATION USAGE"

None.

.SH RATIONALE

The

\fImkdir\fR()

function originated in 4.2 BSD and was added to System V in Release 3.0.

.P

4.3 BSD detects

.BR [ENAMETOOLONG] .

.P

The POSIX.1\(hy1990 standard required that the group ID of a newly created directory be

set to the group ID of its parent directory or to the effective group

ID of the creating process. FIPS 151\(hy2 required that implementations provide

a way to have the group ID be set to the group ID of the containing

directory, but did not prohibit implementations also supporting a way

to set the group ID to the effective group ID of the creating process.

Conforming applications should not assume which group ID will be used. If

it matters, an application can use

\fIchown\fR()

to set the group ID after the directory is created, or determine under

what conditions the implementation will set the desired group ID.

.P

The purpose of the

\fImkdirat\fR()

function is to create a directory in directories other than the

current working directory without exposure to race conditions. Any part

of the path of a file could be changed in parallel to the call to

\fImkdir\fR(),

resulting in unspecified behavior. By opening a file descriptor for

the target directory and using the

\fImkdirat\fR()

function it can be guaranteed that the newly created directory is

located relative to the desired directory.

.SH "FUTURE DIRECTIONS"

None.

.SH "SEE ALSO"

.IR "\fIchmod\fR\^(\|)",

.IR "\fImkdtemp\fR\^(\|)",

.IR "\fImknod\fR\^(\|)",

.IR "\fIumask\fR\^(\|)"

.P

The Base Definitions volume of POSIX.1\(hy2008,

.IR "\fB<sys_stat.h>\fP",

.IR "\fB<sys_types.h>\fP"

.SH COPYRIGHT

Portions of this text are reprinted and reproduced in electronic form

from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology

-- Portable Operating System Interface (POSIX), The Open Group Base

Specifications Issue 7, Copyright (C) 2013 by the Institute of

Electrical and Electronics Engineers, Inc and The Open Group.

(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the

event of any discrepancy between this version and the original IEEE and

The Open Group Standard, the original IEEE and The Open Group Standard

is the referee document. The original Standard can be obtained online at

http://www.unix.org/online.html .

Any typographical or formatting errors that appear

in this page are most likely

to have been introduced during the conversion of the source files to

man page format. To report such errors, see

https://www.kernel.org/doc/man-pages/reporting_bugs.html .