getDirEntries - reading Shore directories

SYNOPSIS
DESCRIPTION
ARGUMENTS
DIRECTORY ENTRIES
ENVIRONMENT
ERRORS
VERSION
SPONSORSHIP
COPYRIGHT
SEE ALSO

SYNOPSIS

const NoSuchCookie;
const TerminalCookie;

VASResult
shore_vas::getDirEntries(
    const    lrid_t     &dir,
    char                *rb,
    ObjectSize          bufbytes,  
    int                 *nresults,
    Cookie              *cookie       
);

DESCRIPTION

GetDirEntries writes sets of directory entries into a caller-provided buffer.

ARGUMENTS

Dir identifies the directory object of interest. Rb is points to the caller's buffer. Bufbytes is the size of the buffer, in bytes. Nresults is a pointer to an integer in the caller's data area, into which the SVAS writes the number of complete entries that were placed in the buffer. Cookie is a pointer to an opaque value that the SVAS places in the caller's data area, and which is used by the SVAS to maintain state between calls to getDirEntries. The caller must set the initial value of *cookie (on the first call) to NoSuchCookie.

TerminalCookie is returned when the last entry has been returned. Thus, there are no more entries to process when *nresults == 0 and *cookie == TerminalCookie.

DIRECTORY ENTRIES

A directory entry is a 5-tuple:

opaque: Four bytes of opaque data.
serial: A serial number, which is Shore's analog of an i-node number.
integer: The length, in bytes, of the entry.
integer: The length, in bytes, of the name.
name: A sequence of characters that constitute the name of the directory entry.

All entries are 8-byte aligned when placed in the caller's buffer.

ENVIRONMENT

GetDirEntries is available on on the server and in the client library. The method acquires locks, so it must be run in transactions.

ERRORS

Deadlocks can occur while locks are being acquired. See transaction(svas) for information about deadlocks.

A complete list of errors is in errors(svas).

VERSION

This manual page applies to Version 1.1.1 of the Shore software.

SPONSORSHIP

The Shore project is sponsored by the Advanced Research Project Agency, ARPA order number 018 (formerly 8230), monitored by the U.S. Army Research Laboratory under contract DAAB07-91-C-Q518.

CONTENTS