The symlink callable service creates a symbolic link to a path name. A file of type "symbolic link" is created.
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. |
|
AMODE 64 callers use BPX4SYM with the same parameters.
The name of a fullword that contains the length of Pathname.
The name of a field, of length Pathname_length, that contains the pathname for which you are creating a symbolic link.
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.
The name of a field that contains the symbolic link that is being created.
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 | 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:
|
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. |
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.
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.
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.
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.
There are no restrictions on the use of the symlink service.
For an example using this callable service, see BPX1SYM (symlink) example.