12.3 Directory Handles

If your particular flavor of operating system provides the readdir library function or its moral equivalent, Perl provides access to that routine (and its companions) using directory handles. A directory handle is a name from yet another namespace, and the cautions and recommendations that apply to filehandles also apply to directory handles (you can't use a reserved word, and uppercase is recommended). The filehandle FRED and the directory handle FRED are unrelated.

The directory handle represents a connection to a particular directory. Rather than reading data (as from a filehandle), you use the directory handle to read a list of filenames within the directory. Directory handles are always opened read-only; you cannot use a directory handle to change the name of a file or to delete a file.

If your library doesn't provide readdir( ) and friends (and you didn't provide a substitute implementation while building Perl), using any of these routines is a fatal error, and your program won't make it past the compilation: it will abort before the first line of code is executed. Perl tries very hard to isolate you from your environment, but it's not a miracle worker.