mkdir (BPX1MKD, BPX4MKD) — Make a directory

Function

The mkdir callable service creates a new, empty directory.

Requirements

Operation Environment
Authorization: Supervisor state or problem state, any PSW key
Dispatchable unit mode: Task
Cross memory mode: PASN = HASN
AMODE (BPX1MKD): 31-bit
AMODE (BPX4MKD): 64-bit
ASC mode: Primary mode
Interrupt status: Enabled for interrupts
Locks: Unlocked
Control parameters: All parameters must be addressable by the caller and in the primary address space.

Format

CALL BPX1MKD,(Pathname_length,
              Pathname,
              Mode,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4MKD with the same parameters.

Parameters

Pathname_length
Supplied parameter
Type:
Character string
Character set:
No restriction
Length:
Fullword

The name of a fullword that contains the length of the full Pathname of the directory. The name can be up to 1023 bytes long. Each component of the name (between delimiters) can be up to 255 bytes long.

Pathname
Supplied parameter
Type:
Character string
Character set:
No restriction
Length:
Specified by the Pathname_length parameter

The name of a field, of length Pathname_length, that contains the full name of the directory.

Pathnames can begin with or without a slash.
  • A pathname that begins with a slash is an absolute pathname. The slash refers to the root directory, and the search for the file starts at the root directory.
  • A pathname that does not begin with a slash is a relative pathname. The search for the file starts at the working directory.
Mode
Supplied parameter
Type:
Structure
Length:
Fullword

The name of a fullword in which the mode field is specified. The mode field specifies the file type and the permissions you grant to yourself, to your group, and to any user.

The file type is identified using the BPXYFTYP mapping macro and permissions that are specified with the BPXYMODE mapping macro. See BPXYFTYP — File type definitions and BPXYMODE — Map the mode constants of the file services.

Return_value
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the mkdir service returns 0 if the request is successful, or -1 if it is not successful.

Return_code
Returned parameter
Type:
Integer
Length:
Fullword
The name of a fullword in which the mkdir service stores the return code. The mkdir service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The mkdir service can return one of the following values in the Return_code parameter:
Return_code Explanation
EACCES The process did not have search permission on some component of Pathname, or did not have write permission on the parent directory of the directory to be created.
EEXIST There is already a file or directory with the given Pathname. The following reason code can accompany the return code: JRMkDirExist.
EFBIG A request to create a directory is prohibited because the file size limit for the process is set to 0.
ELOOP A loop exists in symbolic links that were encountered during resolution of the Pathname argument. This error is issued if more than 24 symbolic links are detected in the resolution of Pathname.
EMLINK The link count of the parent directory has already reached the maximum defined for the system. Refer to the LINK_MAX in pathconf (BPX1PCF, BPX4PCF) — Determine configurable path name variables using a path name, or to fpathconf (BPX1FPC, BPX4FPC) — Determine configurable path name variables using a descriptor.
ENAMETOOLONG Pathname contains more than 1023 characters; or a component of the name is longer than 255 characters.
ENOENT Some component of Pathname does not exist; or the Pathname parameter is blank.
ENOSPC The file system does not have enough space to contain a new directory; or the parent directory cannot be extended.
ENOTDIR A component of Pathname is not a directory.
EROFS The parent directory of the directory to be created is on a read-only file system. The following reason code can accompany the return code: JRMkDirROnly.
Reason_code
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the mkdir service stores the reason code. The mkdir service returns a Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. See z/OS UNIX System Services Messages and Codes for the reason codes.

Usage notes

  1. The file permission bits that are specified through the Mode parameter are modified by the file creation mask of the calling process (see umask (BPX1UMK, BPX4UMK) — Set the file mode creation mask). They are then used to set the file permission bits of the new directory.
  2. The new directory's owner ID is set to the effective user ID (UID) of the calling process.
  3. The file's owner ID is set to the process's effective user ID (UID). By default, the owning GID is set to that of the parent directory. However, if the FILE.GROUPOWNER.SETGID profile exists in the UNIXPRIV class, the owning GID is determined by the set-gid bit of the parent directory, as follows:
    • If the parent's set-gid bit is on, the owning GID is set to that of the parent directory.
    • If the parent's set-gid bit is off, the owning GID is set to the effective GID of the process.
  4. The mkdir service sets the access, change, and modification times for the new directory. It also sets the change and modification times for the directory that contains the new directory.

Related services

Characteristics and restrictions

There are no restrictions on the use of the mkdir service.

Examples

For an example using this callable service, see BPX1MKD (mkdir) example.