mkdir()--Make Directory

 #include <sys/stat.h>

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

The mkdir() function creates a new, empty directory whose name is defined by path. The file permission bits in mode are modified by the file creation mask of the job and then used to set the file permission bits of the directory being created.

For more information on the permission bits in mode see chmod()--Change File Authorizations. For more information on the file creation mask, see umask()--Set Authorization Mask for Job.

The owner ID of the new directory is set to the effective user ID (uid) of the job. If the directory is being created in the "root" (/), QOpenSys, and user-defined file systems, the following applies. If the S_ISGID bit of the parent directory is off, the group ID (GID) is set to the effective GID of the thread creating the directory. If the S_ISGID bit of the parent directory is on, the group ID (GID) of the new directory is set to the GID of the parent directory. For all other file systems, the group ID (GID) of the new directory is set to the GID of the parent directory.

mkdir() sets the access, change, modification, and creation times for the new directory. It also sets the change and modification times for the directory that contains the new directory (parent directory).

The link count of the parent directory link count is increased by one. The link count of the new directory is set to 2. The new directory also contains an entry for "dot" (.) and "dot-dot" (..).

If path names a symbolic link, the symbolic link is not followed, and mkdir() fails with the [EEXIST] error.

If bits in mode other than the file permission bits are set, mkdir() fails with the [EINVAL] error.

Parameters

path

(Input) A pointer to the null-terminated path name of the directory to be created.

This parameter is assumed to be represented in the CCSID (coded character set identifier) currently in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented in the default CCSID of the job.

The name of the new directory is assumed to be represented in the language and country or region currently in effect for the process.

See QlgMkdir()--Make Directory for a description and an example of supplying the path in any CCSID.

mode

(Input) Permission bits for the new directory. The S_ISVTX bit may also be specified when creating the directory.

See chmod()--Change File Authorizations for details on the values that can be specified for mode.

Authorities

Note: Adopted authority is not used.

Authorization Required for mkdir() (excluding QSYS.LIB, Independent ASP QSYS.LIB, and QDLS)

Authorization Required for mkdir() in the QSYS.LIB and independent ASP QSYS.LIB File Systems

Authorization Required for mkdir() in the QDLS File System

Return Value

0

mkdir() was successful. The directory was created.

-1

mkdir() was not successful. The directory was not created. The errno global variable is set to indicate the error.

Error Conditions

If mkdir() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

If interaction with a file server is required to access the object, errno could indicate one of the following errors:

Error Messages

The following messages may be sent from this function:

Usage Notes

1. This function will fail with error code [ENOTSAFE] when all the following conditions are true:
   
   
   • There are secondary threads active in the job.
     
   • The object on which this function is operating resides in a file system that is not threadsafe. Only the following file systems are threadsafe for this function:
     
     
     • "Root" (/)
     • QOpenSys
     • User-defined
     • QNTC
     • QSYS.LIB
     • Independent ASP QSYS.LIB
     • QOPT
     • Network File System
     • QFileSvr.400
   
   
2. "Root" (/), QOpenSys, and User-Defined File System Differences

   The user who creates the directory becomes its owner.

   The S_ISGID bit of the directory affects what the group ID (GID) is for objects that are created in the directory. If the S_ISGID bit of the parent directory is off, the group ID (GID) is set to the effective GID of the thread creating the object. If the S_ISGID bit of the parent directory is on, the group ID (GID) is copied from the parent directory in which the new directory is being created.

   The owner, primary group, and public object authorities (*OBJEXIST, *OBJMGT, *OBJALTER, and *OBJREF) are copied from the parent directory's owner, primary group, and public object authorities. This occurs even when the new directory has a different owner than the parent directory. The owner, primary group, and public data authorities (*R, *W, and *X) are derived from the permissions specified in the mode (except for those permissions that are also set in the file mode creation mask). The new directory does not have any private authorities or authorization list. It only has authorities for the owner, primary group, and public.

   The create object scanning attribute value for this directory is copied from the create object scanning attribute value of the parent directory. For more information on this attribute, see Qp0lSetAttr()--Set Attributes.

   The create object auditing attribute value for this directory will be set to *SYSVAL. For more information on this attribute, see Qp0lSetAttr()--Set Attributes.

   
   
3. QSYS.LIB and Independent ASP QSYS.LIB File System Differences

   The user who creates the directory becomes its owner. The group ID is copied from the primary user ID, if one exists.

   The owner is given *ALL object authority to the new directory. The group object authorities are copied from the user profile of the owner. The public receives no object authority to the directory.

   The primary group authorities specified in mode are not saved if no primary group exists.

   The change and modification times for the directory that contains the new directory are only set when the new directory is a database file.

   The create object auditing attribute value for this directory will be set to *SYSVAL. For more information on this attribute, see Qp0lSetAttr()--Set Attributes.

   
   
4. QDLS File System Differences

   The user who creates the directory becomes its owner. The group ID is copied from the parent folder in which the new directory is being created.

   The object authority of the owner is set to *OBJMGT + *OBJEXIST + *OBJALTER + *OBJREF.

   The primary group and public object authority and all other authorities are copied from the parent folder.

   The owner, primary group, and public data authority (including *OBJOPR) are derived from the permissions specified in mode (except those permissions that are also set in the file mode creation mask).

   The primary group authorities specified in mode are not saved if no primary group exists.

   
   
5. QOPT File System Differences

   When the volume on which the directory is being created is formatted in Universal Disk Format (UDF):
   
   

   • The authorization that is checked for the object and preceding directories in the path name follows the rules described in Authorization Required for mkdir().
   • The volume authorization list is checked for *CHANGE authority.
   • The user who creates the file becomes its owner.
   • The group ID is copied from the parent directory in which the file is created.
   • The owner, primary group, and public data authorities (*R, *W, and *X) are derived from the permissions specified in the mode.
   • The same uppercase and lowercase forms in which the names are entered are preserved. No distinction is made between uppercase and lowercase when searching for names.

   When the volume on which the directory is being created is not formatted in Universal Disk Format (UDF):

   • No authorization is checked on the object or preceding directories in the path name.
   • The volume authorization list is checked for *CHANGE authority.
   • QDFTOWN becomes the owner of the directory.
   • No group ID is assigned to the directory.
   • The permissions specified in the mode are ignored. The owner, primary group, and public data authorities are set to RWX.
   • For newly created directories, names are created in uppercase. No distinction is made between uppercase and lowercase when searching for names.

   A directory cannot be created as a direct child of /QOPT.

   The change and modification times of the parent directory are not updated.

   
   
6. Network File System Differences

   Local access to remote directories through the Network File System may produce unexpected results due to conditions at the server. The creation of a directory may fail if permissions and other attributes that are stored locally by the Network File System are more restrictive than those at the server. A later attempt to create a file can succeed when the locally stored data has been refreshed. (Several options on the Add Mounted File System (ADDMFS) command determine the time between refresh operations of local data.) The creation can also succeed after the file system has been remounted.

   If you try to re-create a directory that was recently deleted, the request may fail because data that was stored locally by the Network File System still has a record of the directory's existence. The creation succeeds when the locally stored data has been updated.

   
   
7. QNTC File System Differences

   Directory authorities are inherited from the access control list (if any exists) of the parent directory. The mode bits are ignored.

   In addition to the normal mkdir() function, in the QNTC file system, mkdir() can be used to add a server directory under the /QNTC directory level. Directories for all functional Windows NT^® servers in the local subnet are automatically created. However, Windows NT servers outside the local subnet must be added by using mkdir() or the MKDIR command. For example:

        char new_dir[]="/QNTC/NTSRV1";
        mkdir(new_dir,NULL)
   

   would add the NTSRV1 server into the QNTC directory structure for future access of files and directories on that server.

   It is also possible to add the server by using the TCP/IP address. For example:

        char new_dir[]="/QNTC/9.130.67.24";
        mkdir(new_dir,NULL)
   

   The directories added using mkdir() in the QNTC file system will not persist across IPLs. Thus, mkdir() or the Make Directory (MKDIR) command must be reissued after every system IPL.

Related Information

• The <sys/stat.h> file (see Header Files for UNIX^®-Type Functions)
  
• chmod()--Change File Authorizations
  
• QlgMkdir()--Make Directory
  
• stat()--Get File Information
  
• umask()--Set Authorization Mask for Job
  
• pathconf()--Get Configurable Path Name Variables

Example

The following example creates a new directory.

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

#include <sys/stat.h>
#include <unistd.h>
#include <stdio.h>

main() {
  char new_dir[]="new_dir";

  if (mkdir(new_dir, S_IRWXU|S_IRGRP|S_IXGRP) != 0)
    perror("mkdir() error");
  else if (chdir(new_dir) != 0)
    perror("first chdir() error");
  else if (chdir("..") != 0)
    perror("second chdir() error");
  else if (rmdir(new_dir) != 0)
    perror("rmdir() error");
  else
    puts("success!");
}

[ Back to top | UNIX-Type APIs | APIs by category ]