unlink (BPX1UNL, BPX4UNL) — Remove a directory entry

Function

The unlink service removes a directory entry. A directory entry can be identified by a pathname to a file, a link name to a file, or a symbolic link.

If a link to a file is removed, and the link count becomes zero, and no other process has the file open, the file itself is deleted.

Requirements

Operation Environment
Authorization: Supervisor or problem state, any PSW key
Dispatchable unit mode: Task
Cross memory mode: PASN = HASN
AMODE (BPX1UNL): 31-bit
AMODE (BPX4UNL): 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

The syntax format is as follows:

AMODE 64 callers use BPX4UNL with the same parameters.

Parameters

Name_length
Supplied parameter
Type:
Integer
Length:
Fullword

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

Name
Supplied parameter
Type:
Character string
Character set:
No restriction
Length:
Specified by the Name_length parameter

The name of a field, of length Name_length, that contains the name of the directory entry that is to be removed. Name can be a pathname to a file, a link name to a file, or a symbolic link name. The pathname was specified when the file was created (see open (BPX1OPN, BPX4OPN) — Open a file). The link name was specified when a link to the file was created (see link (BPX1LNK, BPX4LNK) — Create a link to a file), or when the symbolic link was created (see symlink (BPX1SYM, BPX4SYM) — Create a symbolic link to a path name).

Return_value
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the unlink 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 unlink service stores the return code. The unlink 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 unlink service can return one of the following values in the Return_code parameter:
Return_code Explanation
EACCES One of the following conditions occurred:
  • The calling process does not have permission to search some component of Pathname, or does not have write permission for the directory that contains the link that is to be removed.
  • The S_ISVTX flag is set for the parent directory of the file that is to be removed, and the caller is not the owner of the file or of the parent directory; nor does the caller have appropriate privileges (see Authorization).
EBUSY The file cannot be unlinked because it is being used by the system or the file is open by a remote NFS client with a share reservation that conflicts with the requested operation.
EINVAL The Name parameter is incorrect. It contains a null character.
ELOOP A loop exists in symbolic links that were encountered during resolution of the Name argument. This error is issued if more than 24 symbolic links are detected in the resolution of Name.
ENAMETOOLONG Name is longer than 1023 characters, or some component of the pathname is longer than 255 characters. Name truncation is not supported.
ENOENT Name was not found, or no name was specified. The following reason code can accompany the return code: JRUnlNoEnt.
ENOTDIR Some component of the pathname prefix is not a directory.
EPERM Name refers to a directory. Directories cannot be removed using unlink. The following reason code can accompany the return code: JRUnlDir.
EROFS The link that is to be removed is on a read-only file system. The following reason code can accompany the return code: JRUnlMountRO.
Reason_code
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the unlink service stores the reason code. The unlink 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. If the name that is specified refers to a symbolic link, the symbolic link file that is named by Name is deleted.
  2. If the unlink service request is successful and the link count becomes zero, the file is deleted. The contents of the file are discarded, and the space it occupied is freed for reuse. However, if another process (or more than one) has the file open or in use when the last link is removed, the file is not removed until the last process closes it.
  3. When the unlink service is successful in removing the directory entry and decrementing the link count, whether or not the link count becomes zero, it returns control to the caller with Return_value set to 0. It updates the change and modification times for the parent directory and the change time for the file itself (unless the file is deleted).
  4. Directories cannot be removed using the unlink service. To remove a directory, refer to rmdir (BPX1RMD, BPX4RMD) — Remove a directory.
  5. If the S_ISVTX flag is set for the parent directory of the file that is to be unlinked, one of the following conditions must be true, or the request will fail with EACCES:
    • The caller is the owner of the file to be unlinked
    • The caller is the owner of the parent directory
    • The caller has appropriate privileges (see Authorization)
  6. A file may not be unlinked if it is currently open by a remote NFS client with a share reservation that would prevent the file from being opened for writing. Refer to open (BPX1OPN, BPX4OPN) — Open a file for details about the NFS Share reservations.

Characteristics and restrictions

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

Examples

For an example using this callable service, see BPX1UNL (unlink) example.