rmdir (BPX1RMD, BPX4RMD) — Remove a directory

Function

The rmdir callable service removes a directory. The directory must be empty.

Requirements

Parameters

Directory_name_length

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the length of Directory_name.

Directory_name

Supplied parameter

Type:

Character string

Character set:

No restriction

Length:

Specified by the Directory_name_length parameter

The name of a field that contains the pathname of the directory to be removed. The length of this field is specified in Directory_name_length.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the rmdir 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 rmdir service stores the return code. The rmdir 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 rmdir service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EACCES	One of the following conditions occurred: The process did not have search permission for some component of Directory_name, or did not have write permission for the directory that contains the directory that is to be removed. The S_ISVTX flag is set for the parent directory of the directory that is to be removed, and the caller is not the owner of that directory or the owner of the parent directory, nor does the caller have appropriate privileges (see Authorization).
EBUSY	The directory cannot be removed, because it is being used by a process. The following reason code can accompany the return code: JRRootNode.
EINVAL	The argument that was supplied was incorrect. Examples of incorrect arguments are dot and dot-dot. The following reason code can accompany the return code: JRDotOrDotDot.
ELOOP	A loop exists in symbolic links that were encountered during resolution of the Directory_name argument. This error is issued if more than 24 symbolic links are detected in the resolution of Directory_name.
ENAMETOOLONG	The name of the directory is longer than 1023 characters; or some component of the pathname is longer than 255 characters. This could be as a result of encountering a symbolic link during resolution of Directory_name, where the substituted string is longer than 1023 characters.
ENOENT	The directory that was specified by Directory_name was not found; or no Directory_name parameter was specified. The following reason code can accompany the return code: JRFileNotThere.
ENOTDIR	Some component of Directory_name is not a directory. The following reason code can accompany the return code: JRPathNotDir.
ENOTEMPTY	The directory contains files or subdirectories.
EROFS	The directory that is to be removed is on a read-only file system. The following reason code can accompany the return code: JRReadOnlyFS.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

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

Usage notes

1. The directory must be empty.
2. If the directory is successfully removed, the change and modification times for the parent directory are updated.
3. If the link count of the directory becomes zero and no process has the directory open, the directory itself is deleted. The space that is occupied by the directory is freed for new use, and the contents of the file are lost.
4. If any process has the directory open when the last link is removed, the directory itself is not removed until the last process closes the directory. New files cannot be created under a directory after the last link is removed, even if the directory is still open.
5. If the S_ISVTX flag is set for the parent directory of the directory that is to be removed, one of the following conditions must be true, or the request will fail with EACCES:
   • The caller is the owner of the directory to be removed
   • The caller is the owner of the parent directory
   • The caller has appropriate privileges (see Authorization)

Related services

• mkdir (BPX1MKD, BPX4MKD) — Make a directory
• unlink (BPX1UNL, BPX4UNL) — Remove a directory entry

Characteristics and restrictions

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