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

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 pathname 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 pathname is longer than 255 characters. Name truncation is not supported.
ENOENT A component of the pathname 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 pathname 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

  1. The link service creates a link named Link_name to an existing file named Filename. This provides an alternate pathname 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.
  2. 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.)
  3. Links are allowed only to files, not to directories.
  4. 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.

Related services

Characteristics and restrictions

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

Examples

For an example using this callable service, see BPX1LNK (link) example.