mkdir

Creates a directory.

Format

#include  <stat.h>

int mkdir  (const char *dir_spec, mode_t mode); (ISO POSIX-1)

int mkdir  (const char *dir_spec, mode_t
           mode, . . . ); (DEC C
           Extension)

Arguments

dir_spec

A valid OpenVMS or UNIX style directory specification that may contain a device name. For example:

DBA0:[BAY.WINDOWS]     /*    OpenVMS      */
/dba0/bay/windows      /*   UNIX style    */

This specification cannot contain a node name, file name, file extension, file version, or a wildcard character. The same restriction applies to the UNIX style directory specifications. For more information about the restrictions on UNIX style specifications, see Chapter 1.

mode

A file protection. See the chmod function in this section for information about the specific file protections.

The file protection of the new directory is derived from the mode argument, the process's file protection mask (see the umask function), and the parent-directory default protections.

In a manner consistent with the OpenVMS behavior for creating directories, mkdir never applies delete access to the directory. An application that needs to set delete access should use an explicit call to chmod to set write permission.

See the Description section of this function for more information about how the file protection is set for the newly created directory.

. . .

Represents the following optional arguments. These arguments have fixed position in the argument list, and cannot be arbitrarily placed.
unsigned int uic
The user identification code (UIC) that identifies the owner of the created directory. If this argument is 0, the DEC C RTL gives the created directory the UIC of the parent directory. If this argument is not specified, the DEC C RTL gives the created directory your UIC. This optional argument is specific to the DEC C RTL and is not portable.

unsigned short max_versions
The maximum number of file versions to be retained in the created directory. The system automatically purges the directory keeping, at most, max_versions number of every file.

If this argument is 0, the DEC C RTL does not place a limit on the maximum number of file versions.

If this argument is not specified, the DEC C RTL gives the created directory the default version limit of the parent directory.

This optional argument is specific to the DEC C RTL and is not portable.

unsigned short r_v_number
The volume (device) on which to place the created directory if the device is part of a volume set. If this argument is not specified, the DEC C RTL arbitrarily places the created directory within the volume set. This optional argument is specific to the DEC C RTL and is not portable.

Description

If you do not specify any optional arguments, the DEC C RTL gives the directory your UIC and the default version limit of the parent directory, and arbitrarily places the directory within the volume set. You cannot get the default behavior for the uic or max_versions arguments if you specify any arguments after them.

Note

The way to create files with OpenVMS RMS default protections using the UNIX system-call functions umask, mkdir, creat, and open is to call mkdir, creat, and open with a file-protection mode argument of 0777 in a program that never specifically calls umask. These default protections include correctly establishing protections based on ACLs, previous versions of files, and so on. In programs that do vfork/exec calls, the new process image inherits whether umask has ever been called or not from the calling process image. The umask setting and whether the umask function has ever been called are both inherited attributes.

The file protection supplied by the mode argument is modified by the process's file protection mask in such a way that the file protection for the new directory is set to the bitwise AND of the mode argument and the complement of the file protection mask.

Default file protections are supplied to the new directory from the parent-directory such that if a protection value bit in the new directory is zero, then the value of this bit is inherited from the parent-directory. However, bits in the parent directory's file protection that indicate delete access do not cause corresponding bits to be set in the new directory's file protection.

Return Values

0	Indicates success.
-1	Indicates failure.

Examples

1. umask (0002); /* turn world write access off */
   mkdir ("sys$disk:[.parentdir.childdir]", 0222);  /* turn write access on */
   
   Parent directory file protection:  System:RWD, Owner:RWD, Group:R, World:R
   

   The file protection derived from the combination of the mode argument and the file protection mask set by umask is (0222) & ~(0002), which is 0220. When the parent directory defaults are applied to this protection, the protection for the new directory becomes:

   File protection:    System:RWD, Owner:RWD, Group:RWD, World:R
   

2. umask (0000);
   mkdir ("sys$disk:[.parentdir.childdir]", 0444);  /* turn read access on */
   
   Parent directory file protection:  System:RWD, Owner:RWD, Group:RWD, World:RWD
   

   The file protection derived from the combination of the mode argument and the file protection mask set by umask is (0444) & ~(0000) which is 0444. When the parent directory defaults are applied to this protection, the protection for the new directory is:

   File protection:    System:RW, Owner:RW, Group:RW, World:RW
   

   Note that delete access is not inherited.