symlink (BPX1SYM, BPX4SYM) — Create a symbolic link to a path name

Function

The symlink callable service creates a symbolic link to a path name. A file of type "symbolic link" is created.

Requirements

Operation Environment
Authorization: Supervisor state or problem state, any PSW key
Dispatchable unit mode: Task
Cross memory mode: PASN = HASN
AMODE (BPX1SYM): 31-bit
AMODE (BPX4SYM): 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 BPX1SYM,(Pathname_length,
              Pathname,
              Link_name_length,
              Link_name,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4SYM with the same parameters.

Parameters

Pathname_length
Supplied parameter
Type:
Integer
Length:
Fullword

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

Pathname
Supplied parameter
Type:
Character string
Character set:
No restriction
Length:
Specified by the Pathname_length parameter

The name of a field, of length Pathname_length, that contains the pathname for which you are creating a symbolic link.

path names can begin with or without a slash:
  • A path name that begins with a slash is an absolute path name. The slash refers to the root directory, and the search for the file starts at the root directory.
  • A path name that does not begin with a slash is a relative path name, and the search for the file starts at the parent directory of the symbolic link file.
Link_name_length
Supplied parameter
Type:
Integer
Length:
Fullword

The name of a fullword that contains the length of Link_name. The name can be up to 1023 bytes long; each component of the name (between delimiters) can be up to 255 bytes long.

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 symbolic link that is being created.

Return_value
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the symlink 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 symlink service stores the return code. The symlink 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 symlink service can return one of the following values in the Return_code parameter:
Return_code Explanation
EACCES The requested operation requires writing in a directory with a mode that denies write permission.
EEXIST The link name already exists. The following reason code can accompany the return code: JRSymFileAlreadyExists.
EFBIG A request to create a symbolic link is prohibited because the file size limit for the process is set to 0.
EINVAL This error code may be returned for any of the following reasons:
  • A component of the path prefix of Pathname or the entire path name exceeds the maximum allowed.
  • The value of Pathname_length is less than or equal to zero.
  • A null character appears in Pathname.
  • Link_name has a slash as its last component, which indicates that the preceding component is a directory. A symbolic link cannot be a directory.
The following reason code can accompany the return code: JRCompNotDir, JRInvalidSymLinkCom, JRInvalidSymLinkLen, and JRNullInPath.
ELOOP A loop exists in symbolic links that were encountered during resolution of the Link_name argument. This error is issued if more than 24 symbolic links are detected in the resolution of Link_name.
ENAMETOOLONG Pathname or Link_name is longer than 1023 characters, or some component of that name is longer than 255 characters. Name truncation is not supported.
ENOSPC The directory in which the entry for the symbolic link is being placed cannot be extended; not enough space remains in the file system.
ENOTDIR A component of the path prefix of Link_name is not a directory.
EROFS The requested operation requires writing in a directory 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 symlink service stores the reason code. The symlink 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 symlink service creates a symbolic link (Link_name) with the file that you specify by Pathname.
  2. Like a hard link (described in link (BPX1LNK, BPX4LNK) — Create a link to a file), a symbolic link allows a file to have more than one name. The presence of a hard link guarantees the existence of a file, even after the original name has been removed. A symbolic link, however, provides no such assurance; in fact, the file identified by Pathname need not exist when the symbolic link is created. In addition, a symbolic link can cross file system boundaries.
  3. When a component of a path name refers to a symbolic link rather than to a directory, the path name that is contained in the symbolic link is resolved. If the path name in the symbolic link begins with / (slash), the symbolic link path name is resolved relative to the process root directory. If the path name in the symbolic link does not begin with /, the symbolic link path name is resolved relative to the directory that contains the symbolic link.
  4. If the symbolic link is not the last component of the original path name, remaining components of the original path name are resolved from there.

    When a symbolic link is the last component of a path name, it may or may not be resolved. Resolution depends on the function that is using the path name. For example, a rename request does not have a symbolic link resolved when it appears as the final component of the new or old path name. However, an open request does have a symbolic link resolved when it appears as the last component.

    When a slash is the last component of a path name, and it is preceded by a symbolic link, the symbolic link is always resolved.

  5. Because the mode of a symbolic link cannot be changed, its mode is ignored during the lookup process. Any files and directories to which a symbolic link refers are checked for access permission.
  6. Sysplex members participating in a shared file system can access (read/write) file system data on other systems in the sysplex. For example, if SY1 and SY2 are two systems in a sysplex, a user on SY1 can access SY2's /etc directory.
    The shared file system capability requires that /etc, /dev, /var, and /tmp be converted into symbolic links. If the content of the symbolic link begins with $VERSION, $SYSNAME, $SYSSYMR, or $SYSSYMA, the symbolic link will resolve in a specific manner:
    • If the content of the symbolic link begins with $SYSNAME and the BPXPRMxx parameter SYSPLEX is specified YES, $SYSNAME is replaced with a slash followed by the system name (/SY1). If SYSPLEX(NO) is specified, $SYSNAME is replaced with /SYSTEM. For example, if you have specified SYSPLEX(YES) and the symbolic link for /etc has the contents $SYSNAME/etc, this will resolve to /SY1/etc on a system whose name is SY1, and will resolve to /SY2/etc on a system whose name is SY2.
    • If the content of the symbolic link begins with $VERSION, $VERSION will resolve to the value specified on the VERSION parameter in BPXPRMxx. Thus, if VERSION in parmlib is set to REL9, resolution of a symbolic link with $VERSION causes $VERSION to be replaced with /REL9. For example, the symbolic link for /bin, which has the contents $VERSION/bin, will resolve to /REL9/bin on a system whose $VERSION value is set to REL9.
    • When a component of the path name is a symlink that begins with $SYSSYMR or $SYSSYMA, any MVS™ static symbols in the template are replaced with the resolved substitution text. In the following examples, &SYSR1 is an MVS static symbol:
      • If the content of the symbolic link begins with $SYSSYMR, $SYSSYMR/ results in a relative path name; that is, the lookup proceeds from its current position in the path name. For example, if the symlink is /x/y/sym1 and the symlink contains $SYSSYMR/&SYSR1./resdir, a path name lookup on /x/y/sym1 from SY1 will resolve the symlink to OSV315/resdir. Because it is a relative path name (the identifier was $SYSSYMR/), the resulting path name will be /x/y/OSV315/resdir.
      • If the content of the symbolic link begins with $SYSSYMA, $SYSSYMA/ results in an absolute path name; that is, the lookup starts over at the root. For example, if the symlink is /x/y/sym1 and the symlink contains $SYSSYMA/&SYSR1./resdir, a path name lookup on /x/y/sym1 from SY1 will resolve the symlink to /OSV315/resdir. Because it is an absolute path name (the identifier was $SYSSYMA/), the resulting path name will be /OSV315/resdir.

      Only the occurrence of $SYSSYMR/ or $SYSSYMA/ at the start will be recognized as an identifier for which the remaining text requires substitution. Any other identifiers after the beginning will remain as is in the resolved linkname. There must be some text following a $SYSSYMR/ or $SYSSYMA/ for it to be recognized as a valid identifier with text containing symbols to be resolved.

    If the content of the symbolic link begins with $SYSSECA/ or $SYSSECR/, the user's current security label is substituted into the path name. The symbol $SYSSECA indicates that the user's current security label should be substituted into the path name as an absolute directory name. Pathname resolution continues at the ROOT with a directory name of the user's current security label. The symbol $SYSSECR indicates that the user's current security label should be substituted into the path name as a relative directory. The path name resolution continues in the directory in which the symbolic link is encountered, with a directory name of the user's current security label. For more information about using security labels, see z/OS Planning for Multilevel Security and the Common Criteria.

    For more information about file system sharing in a sysplex, see Shared file systems in a sysplex in z/OS UNIX System Services Planning. The SYSPLEX(YES|NO) and VERSION('nnnn') BPXPRMxx parameters are described in z/OS MVS Initialization and Tuning Reference.

  7. Certain directories like /etc, /dev, /tmp, and /var are converted to symbolic links. Some shell commands have minor technical differences when referring to symbolic links than for regular files or directories. For example, ls does not follow symbolic links by default. /etc is a symbolic link, so ls /etc will display only the symbolic link name, in this case /etc.

    In order to follow symbolic links, you must specify ls -L or provide a trailing slash. For example, ls -L /etc and ls /etc/ both display the files in the directory that the /etc symbolic link points to.

    Other shell commands that have differences due to symbolic links are du, find, pax, rm and tar.

  8. By default, the owning GID of the symbolic link is set to that of the parent directory. However, if the FILE.GROUPOWNER.SETGID profile exists in the UNIXPRIV class, the owning GID is determined by the set-gid bit of the parent directory, as follows:
    • If the parent's set-gid bit is on, the owning GID is set to that of the parent directory.
    • If the parent's set-gid bit is off, the owning GID is set to the effective GID of the process.

Related services

Characteristics and restrictions

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

Examples

For an example using this callable service, see BPX1SYM (symlink) example.

Parent topic: Callable services descriptions