scandir or alphasort Subroutine

AIX Version 4.3 Base Operating System and Extensions Technical Reference, Volume 2

scandir or alphasort Subroutine

Purpose

Scans or sorts directory contents.

Library

Standard C Library (libc.a)

Syntax

#include <sys/types.h>
#include <sys/dir.h>

int scandir(DirectoryName,NameList,Select,Compare)
char *DirectoryName;
struct dirent * (*NameList [ ]);
int (*Select) (struct dirent *);
int (*Compare)(void *, void *);

int alphasort (Directory1,Directory2)
void *Directory1, *Directory2;

Description

The scandir subroutine reads the directory pointed to by the DirectoryName parameter, and then uses the malloc subroutine to create an array of pointers to directory entries. The scandir subroutine returns the number of entries in the array and, through the NameList parameter, a pointer to the array.

The Select parameter points to a user-supplied subroutine that is called by the scandir subroutine to select which entries to include in the array. The selection routine is passed a pointer to a directory entry and should return a nonzero value for a directory entry that is included in the array. If the Select parameter is a null value, all directory entries are included.

The Compare parameter points to a user-supplied subroutine. This routine is passed to the qsort subroutine to sort the completed array. If the Compare parameter is a null value, the array is not sorted. The alphasort subroutine provides comparison functions for sorting alphabetically.

The memory allocated to the array can be deallocated by freeing each pointer in the array, and the array itself, with the free subroutine.

The alphasort subroutine treats Directory1 and Directory2 as pointers to dirent pointers and alphabetically compares them. This subroutine can be passed as the Compare parameter to either the scandir subroutine or the qsort subroutine, or a user-supplied subroutine can be used.

Parameters

DirectoryName	Points to the directory name.
NameList	Points to the array of pointers to directory entries.
Select	Points to a user-supplied subroutine that is called by the scandir subroutine to select which entries to include in the array.
Compare	Points to a user-supplied subroutine that sorts the completed array.
Directory1, Directory2	Point to dirent structures.

Return Values

The scandir subroutine returns the value -1 if the directory cannot be opened for reading or if the malloc subroutine cannot allocate enough memory to hold all the data structures. If successful, the scandir subroutine returns the number of entries found.

The alphasort subroutine returns the following values:

Less than 0	The dirent structure pointed to by the Directory1 parameter is lexically less than the dirent structure pointed to by the Directory2 parameter.
0	The dirent structures pointed to by the Directory1 parameter and the Directory2 parameter are equal.
Greater than 0	The dirent structure pointed to by the Directory1 parameter is lexically greater than the dirent structure pointed to by the Directory2 parameter.

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

Related Information

The malloc, free, realloc, calloc, mallopt, mallinfo, or alloca subroutine, opendir, readdir, telldir, seekdir, rewinddir, or closedir subroutine, qsort subroutine.

Files, Directories, and File Systems for Programmers in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.