Function

The v_readdir service accepts a vnode token that represents a directory and returns as many directory entries from this directory as will fit in the caller's buffer.

Requirements

Parameters

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 to read directory entries from.

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).

UIO

Supplied and returned parameter

Type:

Structure

Length:

Fuio#Len (from the BPXYFUIO macro)

The name of an area that contains the user input and output block. This area is mapped by the BPXYFUIO macro (see BPXYMODE in Mapping macros in z/OS UNIX System Services Programming: Assembler Callable Services Reference).

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the v_readdir service returns the number of directory entries that were returned 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_readdir service stores the return code. The v_readdir 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_readdir 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 read a specified directory.
EINVAL	Parameter error; for example, a supplied area was too small. The following reason codes can accompany the return code: JRInvalidFuio, JrBytes2RWZero, JRVTokenFreed, JRWrongPID, JRStaleVnodeTok, JRInvalidVnodeTok, JRInvalidOSS
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.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the v_readdir service stores the reason code. The v_readdir service returns 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

1. For an overview of the process of reading from directories, see Reading directories.
2. Two protocols are supported for reading through large directories with successive calls:
   • The cursor protocol. The cursor, or offset, that is returned in the UIO by the v_readdir service contains file-system-specific information that locates the next directory entry. The cursor and buffer must be preserved by the caller from one v_readdir call to the next, and reading proceeds based on the cursor.
   • The index protocol. The index that is set in the UIO by the caller determines which entry to start reading from. To read through the directory, the caller starts at one and increments the index by the number of entries that were returned on the previous call.
3. The following UIO fields are provided to specify the details of the read directory request:

   FuioID

   Contains Fuio#ID (from the BPXYFUIO macro).

   FuioLen

   Contains the length of the UIO structure.

   FuioChkAcc

   Requests the PFS to perform required access checking before performing the requested readdir operation.

   FuioBufferAddr

   Contains the address of a buffer where the directory entries are to be returned.

   FuioBuff64Vaddr

   Contains the 64-bit virtual address of a buffer where the directory entries are to be returned.

   FuioIBytesRW

   Specifies the maximum number of bytes that can be written to the output buffer.

   FuioRDIndex

   Specifies the first directory entry that is to be returned when the index protocol is used.

   FuioCursor

   When the cursor protocol is used, this specifies a value that was returned on the previous v_readdir call and that indicates the next entry to be read, or 0 on the first call.

   FuioRddPlus

   Indicates that the request is for the ReaddirPlus function. The attributes for each entry should be included in the output.

4. The following UIO fields are returned by the v_readdir service:

   FuioPSWKey

   Is set to the caller's key.

   FuioCursor

   Is set to the cursor value representing the directory position. This value is used if the next call uses the cursor protocol.

   FuioCVerRet

   Indicates that the Cookie Verifier (FuioCVer) is being returned.

   FuioCVer

   When FuioCVerRet is on, this field is set to the Cookie Verifier for the directory that is being read. When a directory is being read with multiple reads, you can use the FuioCVer that is returned to compare each Cookie Verifier with the last one. If the directory has been modified between reads, you can reject the request because the results will not be valid.

5. The buffer contents that are returned by the v_readdir service are mapped by BPXYDIRE macro (see Mapping macros in z/OS UNIX System Services Programming: Assembler Callable Services Reference).
6. The FuioAddr64 setting determines whether the pointer to the user buffer is a 64-bit pointer in FuioBuff64Vaddr or a 31-bit pointer in FuioBufferAddr.
7. The OssXmtpt flag allows a v_readdir operation to cross mount points when the FuioRddPlus flag is set. Normally, the attributes that are returned with each name are for objects in the same file system as the directory being read. However, some of the objects may be mount point directories. To have the attributes of the mounted root directory returned (instead of the attributes of the mount point), set the OssXmtpt flag in the input OSS structure. When the directory being read is the root of a mounted file system (but not the system root), the attributes for the “..” entry will be replaced with the attributes of the parent of the underlying mount point. In such cases, the device number in the Attrdev field in that entry's attributes will differ from the device number of the directory being read and the VFS_Token of the other file system will be returned in the AttrCharSetID field.
8. When the OssNoRemote flag and the OssXmtpt flag are both set, v_readdir will not cross over into a remote file system. Remote file systems are NFS Client and DFS Client file systems. If a remote file system is encountered the attributes that are returned will be those of the original object; that is, the mount point rather than the mounted root, and for the ".." entry in a root, the root's attributes will be returned.

Related services

• v_reg (BPX1VRG, BPX4VRG) — Register a process as a server

Characteristics and restrictions

A process must be registered as a server before the v_readdir service is permitted; see v_reg (BPX1VRG, BPX4VRG) — Register a process as a server.