|
FunctionThe v_symlink service creates a
symbolic link to a path name or external name. A file whose name is
specified in the Link_name parameter, of type "symbolic link",
is created within the directory that is represented by Directory_vnode_token.
The contents of the symbolic link file is the path name or external
name that is specified in Pathname.
RequirementsOperation |
Environment |
---|
Authorization: |
Supervisor state or problem state, any PSW key |
Dispatchable unit mode: |
Task |
Cross memory mode: |
PASN = HASN |
AMODE (BPX1VSY): |
31-bit |
AMODE (BPX4VSY): |
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. |
FormatCALL BPX1VSY,(Directory_vnode_token,
OSS,
Link_name_length,
Link_name,
Pathname_length,
Pathname,
Attr_length,
Attr,
Return_value,
Return_code,
Reason_code)
AMODE 64 callers use BPX4VSY with the same parameters.
Parameters- Directory_vnode_token
- Supplied parameter
- Type:
- Token
- Length:
- 8 bytes
The name of an 8-byte area that contains a vnode
token that represents the directory in which the v_symlink service
creates the new symbolic link file that is named in the Link_name
parameter.
- OSS
- Supplied and returned parameter
- Type:
- Structure
- Length:
- OSS#LENGTH (from the BPXYOSS macro)
The name of an area that contains operating-system-specific
parameters. This area is mapped by the BPXYOSS macro (see BPXYOSS — Map operating system specific information).
- Link_name_length
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword that contains the length
of Link_name. The Link_name can be up to 255 bytes long.
- Link_name
- Supplied parameter
- Type:
- Character string
- Length:
- Specified by Link_name_length parameter
The name of a field that contains the symbolic
link that is being created. It must not contain null characters (X'00').
- Pathname_length
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword that contains the length
of Pathname. The Pathname can be up to 1023 bytes long. If the Pathname
is not an external name (AttrExtLink = 0), each component of the name
(between delimiters) can be up to 255 bytes long.
- Pathname
- Supplied parameter
- Type:
- Character string
- Length:
- Specified by the Pathname_length parameter
The name of a field that contains the path name
or external name for which you are creating a symbolic link.
A
path name can begin with or without a slash. - If the path name begins with a slash, it is an absolute path name,
the slash refers to the root directory, and the search for the file
starts at the root directory.
- If the path name does not begin with a slash, it is a relative
path name, and the search for the file starts at the parent directory
of the symbolic link file.
A path name must not contain null characters (X'00').
An
external name is the name of an object that is outside the hierarchical
file system. There are no restrictions on the characters that may
be used in an external name.
- Attr_length
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword that contains the length
of Attr. To determine the value of Attr_length, use the ATTR structure
(see BPXYATTR — Map file attributes for v_ system calls).
- Attr
- Supplied parameter
- Type:
- Structure
- Length:
- Specified by the Attr_length parameter
The name of an area, of length Attr_length, that
is to be used by the v_symlink service to set the attributes of the
file that is to be created. This area is mapped by the ATTR structure
(see BPXYATTR — Map file attributes for v_ system calls).
- Return_value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the v_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 v_symlink service
stores the return code. The v_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 v_symlink
service can return one of the following values in the Return_code
parameter: Return_code |
Explanation |
---|
EACCES |
The calling process does not have permission to write in the
directory specified. |
EEXIST |
Link_name already exists. |
EFBIG |
The file size limit for the process is set to zero, prohibiting
the creation of symbolic links. |
EINVAL |
Parameter error; for example, a supplied area was too small.
The following reason codes can accompany the return code: JRSmallAttr,
JRInvalidAttr, JRNoName, JRInvalidSymLinkLen, JRNULLInPath, JRInvalidSymLinkComp,
JRVTokenFreed, JRWrongPID, JRStaleVnodeTok, JRInvalidVnodeTok, JRInvalidOSS. |
ENAMETOOLONG |
Link_name is longer than 255 characters. |
ENOTDIR |
The supplied token did not represent a directory. |
EPERM |
The operation is not permitted. The caller of the service is
not registered as a server. |
EROFS |
Directory_vnode_token specifies a directory on a read-only
file system. |
- Reason_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the v_symlink service
stores the reason code. The v_symlink service returns a Reason_code
only if Return_value is -1. Reason_code further
qualifies the Return_code value. See z/OS UNIX System Services Messages and Codes
for the reason codes.
Usage notes- The following Attr fields are provided by the caller:
- AttrID
- Contains Attr#ID (from the ATTR structure)
- AttrLen
- Specifies the length of the ATTR structure.
- AttrExtLink
- Specifies whether the Pathname is an external name (1) or a path
name in a hierarchical file system (0).
- AttrMode
- Specifies directory mode permission bits. See Mapping
macros in z/OS UNIX System Services Programming: Assembler Callable Services Referencefor
the mapping of this field.
Other fields in the ATTR should be set to zeros.
- Like a hard link (described in v_link (BPX1VLN, BPX4VLN) — 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, and can refer to objects that are
outside a hierarchical file system.
- When a component of a path name refers to a symbolic link (but
not an external symbolic link) rather than to a directory, the path
name that is contained in the symbolic link is resolved. When the
VFS callable services API, v_rpn, or other z/OS UNIX callable services
are being used, a symbolic link in a path name parameter is resolved
as follows:
- 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.
- 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
either 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.
- The mode of a symbolic link is ignored during the lookup process.
Any files and directories to which a symbolic link refers are checked
for access permission.
- The external name that is contained in an external symbolic link
is not resolved. Link_name cannot be used as a directory component
of a path name.
- If the file size limit for the process is set to zero, symbolic
link creation is prohibited and fails with EFBIG.
- The value that is set by umask() for the process
does not affect the setting of the mode permission bits.
|