NAME

Linux:Perl::getdents - read full directory information

SYNOPSIS

    #Platform-specific invocation uses e.g.:
    #   Linux::Perl::getdents::arm->getdents(...)

    my @entities = Linux::Perl::getdents->getdents( $filehandle, $buffer_size );

DESCRIPTION

This module provides support for the kernel-level logic to read directories.

Directories store more than just the node names that Perl’s readdir() returns; for example, they store the file type and node number. By calling the kernel’s getdents logic directly, you can get this information without making additional system calls.

METHODS

In addition to the following, this module exposes the constants DT_UNKNOWN() et al. (cf. man 2 getdents)

@ENTRIES = CLASS->getdents( $FILEHANDLE_OR_FD, $READ_SIZE )

Reads from the given $FILEHANDLE_OR_FD using a buffer of $READ_SIZE bytes. There’s no good way to know how many @ENTRIES you can receive given the $READ_SIZE, unfortunately.

The return is a list of hash references; each hash contains the keys ino, off, type, and name. These correspond with the relevant parts of struct linux_dirent64 (cf. man 2 getdents).

(In scalar context, this returns the number of hash references that would be returned in list context.)

For now, this is implemented via the getdents64 system call.

NOTE: Perl 5.20 and earlier doesn’t understand fileno() on a directory handle, so to use this function you’ll need to pass the file descriptor rather than the handle. (To get the file descriptor, you can parse /proc/$$/fd for the symlink that refers to the directory’s path. See this module’s tests for an implementation of this.)