Function
The vn_readdir operation reads
entries from the directory that is represented by the input Token_structure,
and returns as many entries as will fit in the caller's buffer.
Input parameter format
vn_readdir (Token_structure,
OSI_structure,
Audit_structure,
User_IO_structure,
Return_value,
Return_code,
Reason_code)
Parameters
- Token_structure
- Supplied parameter
- Type:
- TOKSTR
- Length:
- Specified by TOKSTR.ts_hdr.cblen.
The Token_structure represents the file (vnode)
that is being operated on. It contains the PFS's initialization token,
mount token, and the file token. Refer to LFS/PFS control block structure for
a discussion of this structure, and to the TOKSTR typedef in BPXYPFSI
in Interface structures for C language servers and clients for its mapping.
- OSI_structure
- Supplied and returned parameter
- Type:
- OSI
- Length:
- Specified by OSI.osi_hdr.cblen.
The OSI_structure contains information that is
used by the OSI operations that may be called by the PFS. See OSI services for more information.
It also contains
MVS-specific information that needs to be passed to the PFS, including
SMF accounting fields, a work area, a recovery area, and an optional
pointer to an output ATTR structure. For more information about the
OSI structure, see The OSI structure.
This area
is mapped by the OSI typedef in BPXYPFSI in Interface structures for C language servers and clients.
- Audit_structure
- Supplied parameter
- Type:
- CRED
- Length:
- Specified by CRED.cred_hdr.cblen.
The Audit_structure contains information that is
used by the security product for access checks and auditing. It is
passed to most SAF routines that are invoked by the PFS.
Refer
to Security responsibilities and considerations for a discussion of security processing,
and to the CRED typedef in BPXYPFSI in Interface structures for C language servers and clients for
the mapping of this structure.
- User_IO_structure
- Supplied and returned parameter
- Type:
- UIO
- Length:
- Specified by UIO.u_hdr.cblen.
An area containing the parameters for the I/O that
is to be performed. This area is mapped by the UIO typedef in the
BPXYVFSI header file (see Interface structures for C language servers and clients). See "Specific
processing notes" for details on how the fields in this structure
are processed.
- Return_value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
A fullword in which the vn_readdir operation returns
the results of the operation, as one of the following return codes:
- Return_value
- Meaning
- -1
- The operation was not successful. The Return_code and Reason_Code
values must be completed by the PFS when Return_value is -1.
- 0
- The operation was successful, and there are no more directory
entries to be read. No entries are returned.
- 0 or greater
- The operation was successful; the value represents the number
of directory entries that are returned.
- Return_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
A fullword in which the vn_readdir operation stores
the return code. The vn_readdir operation returns Return_code only
if Return_value is -1. For a complete list of supported
return code values, see z/OS UNIX System Services Messages and Codes.
The vn_readdir operation must support at least the following
error values:
Return_code |
Explanation |
---|
EACCES |
The caller does not have search permission for the directory. |
EFAULT |
A buffer address that was specified is not in addressable storage. |
EINVAL |
There was a parameter error, such as an input buffer that is
too small for any entries. |
- Reason_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
A fullword in which the vn_readdir operation stores
the reason code. The vn_readdir operation returns Reason_code only
if Return_value is -1. Reason_code further qualifies
the Return_code value. These reason codes are documented by the PFS
product.
Implementation notes
- Overview of vn_readdir processing
Reading directories provides an overview of readdir
operation.
- Specific processing notes
The token structure that is passed on input represents the
directory that is to be read.
The following UIO fields are provided
by the LFS:
- UIO.u_hdr.cbid
- Contains UIO_ID (from the BPXYVFSI header file)
- UIO.u_hdr.cblen
- Specifies the length of the user_IO_structure
- UIO.u_buffaddr
- Specifies the address of the caller's buffer
- UIO.u_alet
- Specifies the ALET of the caller's buffer
- UIO.u_offseth
- Specifies the high-order word of the cursor
- UIO.u_offset
- Specifies the low-order word of the cursor
- UIO.u_count
- Specifies the maximum number of bytes that can be written to the
caller's buffer
- UIO.u_asid
- Specifies the ASID of the caller
- UIO.u_key
- Specifies the storage key of the caller's buffer
- UIO.u_rdindex
- Specifies the readdir index field
- Serialization provided by the LFS
The vn_readdir operation is invoked with a shared latch held
on the vnode of the directory.
- Security calls to be made by the PFS
The PFS is expected to invoke SAF's Check Access callable service
to verify that the user has read permission to the directory.
For
a discussion of vn_link processing in a multilevel security environment,
see PFS support for multilevel security.