link (BPX1LNK, BPX4LNK) — Create a link to a file

Function

The link callable service creates a link to a file. The link is a new name that identifies an existing file. The new name does not replace the old one; it provides an additional way to refer to the file. To rename an existing file, see rename (BPX1REN, BPX4REN) — Rename a file or directory.

Requirements

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

CALL BPX1LNK,(Filename_length,
              Filename,
              Link_name_length,
              Link_name,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4LNK with the same parameters.

Parameters

Filename_length

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the length of the Filename of the existing file.

Filename

Supplied parameter

Type:: Character string
Character set:: No restriction
Length:: Specified by the Filename_length parameter

The name of a field of length Filename_length that contains the name of the existing file to which a link is to be established.

Link_name_length

Supplied parameter

Type:: Integer
Length:: Fullword

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

Link_name

Supplied parameter

Type:: Character string
Character set:: No restriction
Length:: Specified by the Link_name_length parameter

The name of a field that contains the link name by which the file is to be known.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

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

Return_code	Explanation
EACCES	The process did not have appropriate permissions to create the link. Possible reasons include: No search permission for a path name component of Filename or Link_name No write permission for the directory intended to contain the link No permission to access Filename
EEXIST	A file, directory, or symbolic link named Link_name already exists. The following reason code can accompany the return code: JRLnkNewPathExists.
EINVAL	The Filename or Link_name is incorrect because it contains a null.
ELOOP	A loop exists in symbolic links that were encountered during resolution of the Filename or Link_name argument. This error is issued if more than 24 symbolic links are detected in the resolution of Filename or Link_name.
EMLINK	Filename already has its maximum number of links. The maximum number is LINK_MAX. The value of LINK_MAX can be determined through pathconf (BPX1PCF, BPX4PCF) — Determine configurable path name variables using a path name, or fpathconf (BPX1FPC, BPX4FPC) — Determine configurable path name variables using a descriptor.
ENAMETOOLONG	Filename or Link_name is longer than 1023 characters; or some component of the path name is longer than 255 characters. Name truncation is not supported.
ENOENT	A component of the path name that was specified by Filename or Link_name was not found; the file specified by Filename was not found; or one of the two arguments is missing. The following reason code can accompany the return code: JRLnkNoEnt.
ENOSPC	The directory intended to contain the link cannot be extended to contain another entry.
ENOTDIR	A path name component of one of the arguments is not a directory.
EPERM	Filename is the name of a directory; links to directories are not allowed. The following reason code can accompany the return code: JRLnkDir.
EROFS	Creating the link would require writing on a read_only file system. The following reason code can accompany the return code: JRLnkROFileset.
EXDEV	Filename and Link_name are on different file systems. z/OS UNIX does not support links between file systems. The following reason code can accompany the return code: JRLnkAcrossFilesets.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the link service stores the reason code. The link 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

The link service creates a link named Link_name to an existing file named Filename. This provides an alternate path name for the existing file; the file can be accessed by the old name or the new name. The link can be stored in the same directory as the original file, or in a different directory.
If the link is created successfully, the service increments the link count of the file. The link count shows how many links exist for a file. (If the link is not created successfully, the link count is not incremented.)
Links are allowed only to files, not to directories.
If the link is created successfully, the change time of the linked-to file is updated. The change and modification times of the directory that holds the link are also updated.

link (BPX1LNK, BPX4LNK) — Create a link to a file

Function

Requirements

Format

Parameters

Usage notes

Related services

Characteristics and restrictions

Examples