getdirentry

OS/161 Reference Manual

Name

getdirentry - read filename from directory

Library

Standard C Library (libc, -lc)

Synopsis

#include <unistd.h>

int
getdirentry(int fd, char *buf, size_t buflen);

Description

getdirentry retrieves the next filename from a directory referred to by the file handle filehandle. The name is stored in buf, an area of size buflen. The length of of the name actually found is returned.

Note: this call behaves like read() - the name stored in buf is not null-terminated.

Which filename is the "next" is chosen based on the seek pointer associated with the file handle. The meaning of the seek pointer on a directory is defined by the filesystem in use and should not be interpreted - the only ways in which lseek should be used are with SEEK_SET and an offset previously returned by lseek, or with any of SEEK_SET, SEEK_CUR, or SEEK_EOF with an offset of 0.

getdirentry (like all system calls) should be atomic. In this case this means that each getdirentry call should return a name that was in the directory at the point in time when the call happened relative to other calls. getdirentry should never return names that have only been partially written or that have been partially erased. Note that the kernel is not obliged to (and generally cannot) make the getdirentry call atomic with respect to other threads in the same process accessing the transfer buffer during the operation.

In general it is desirable for directory iteration to be stable; that is, opening a directory and reading it should yield a consistent snapshot of the directory state. Implementing this is a nuisance in general, and is worse in OS/161 since the system call we have can only return one name at a time. Therefore, it isn't required by default. (However, always check your course materials for the official word, just in case.)

Return Values

On success, getdirentry returns the length of the name transferred. On error, -1 is returned, and errno is set according to the error encountered.

Errors