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

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.

Related services

• close (BPX1CLO, BPX4CLO) — Close a file
• link (BPX1LNK, BPX4LNK) — Create a link to a file
• open (BPX1OPN, BPX4OPN) — Open a file
• rename (BPX1REN, BPX4REN) — Rename a file or directory
• rmdir (BPX1RMD, BPX4RMD) — Remove a directory

Characteristics and restrictions

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