MKDIR(3P)                                           POSIX Programmer's Manual                                          MKDIR(3P)



PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may differ (con-
       sult the corresponding Linux manual page for details of Linux behavior), or the  interface  may  not  be  implemented  on
       Linux.

NAME
       mkdir - make a directory

SYNOPSIS
       #include <sys/stat.h>

       int mkdir(const char *path, mode_t mode);


DESCRIPTION
       The  mkdir() function shall create a new directory with name path. The file permission bits of the new directory shall be
       initialized from mode. These file permission bits of the mode argument shall be modified by the  process'  file  creation
       mask.

       When  bits  in  mode other than the file permission bits are set, the meaning of these additional bits is implementation-
       defined.

       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.

       The newly created directory shall be an empty directory.

       If path names a symbolic link, mkdir() shall fail and set errno to [EEXIST].

       Upon  successful  completion, mkdir() shall mark for update the st_atime, st_ctime, and st_mtime fields of the directory.
       Also, the st_ctime and st_mtime fields of the directory that contains the new entry shall be marked for update.

RETURN VALUE
       Upon successful completion, mkdir() shall return 0. Otherwise, -1 shall be returned, no directory shall be  created,  and
       errno shall be set to indicate the error.

ERRORS
       The mkdir() function shall fail if:

       EACCES Search  permission is denied on a component of the path prefix, or write permission is denied on the parent direc-
              tory of the directory to be created.

       EEXIST The named file exists.

       ELOOP  A loop exists in symbolic links encountered during resolution of the path argument.

       EMLINK The link count of the parent directory would exceed {LINK_MAX}.

       ENAMETOOLONG
              The length of the path argument exceeds {PATH_MAX} or a pathname component is longer than {NAME_MAX}.

       ENOENT A component of the path prefix specified by path does not name an existing directory or path is an empty string.

       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.

       ENOTDIR
              A component of the path prefix is not a directory.

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


       The mkdir() function may fail if:

       ELOOP  More than {SYMLOOP_MAX} symbolic links were encountered during resolution of the path argument.

       ENAMETOOLONG
              As  a  result  of  encountering  a symbolic link in resolution of the path argument, the length of the substituted
              pathname string exceeded {PATH_MAX}.


       The following sections are informative.

EXAMPLES
   Creating a Directory
       The following example shows how to create a directory named /home/cnd/mod1, with read/write/search permissions for  owner
       and group, and with read/search permissions for others.


              #include <sys/types.h>
              #include <sys/stat.h>


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

APPLICATION USAGE
       None.

RATIONALE
       The mkdir() function originated in 4.2 BSD and was added to System V in Release 3.0.

       4.3 BSD detects [ENAMETOOLONG].

       The  POSIX.1-1990  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-2 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 support-
       ing 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 chown() to set the group ID after the directory
       is created, or determine under what conditions the implementation will set the desired group ID.

FUTURE DIRECTIONS
       None.

SEE ALSO
       umask(), the Base Definitions volume of IEEE Std 1003.1-2001, <sys/stat.h>, <sys/types.h>

COPYRIGHT
       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003  Edition,  Standard  for
       Information  Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copy-
       right (C) 2001-2003 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. 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.open-
       group.org/unix/online.html .



IEEE/The Open Group                                           2003                                                     MKDIR(3P)