mkdir

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  directory  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

       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  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 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.
       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.opengroup.org/unix/online.html .



IEEE/The Open Group                  2003                             MKDIR(P)