scandir(3) manual page wrong

[John Bruner]

I think I complained about this three years ago regarding the scandir
manual page for 4.3BSD.  SunOS 3.2 had the same error.  It's different in
OS 4.0.x, but it is still wrong.  The declaration for the second argument
to scandir() is documented as

	struct direct **namelist;

In fact, it should be a pointer to a pointer to an array of structure
pointers, or

	struct direct ***namelist;

The documentation should also refer to <sys/dirent.h> and "struct dirent".

This is confusing because of the multiple levels of indirection and
arrays, and should be accompanied by an example.  If the manual authors
can't get the definitions right, how is the poor user going to do so?

My suggestion for an example would be something like the following, which
lists the files in the current directory in alphabetical order:

#include <sys/types.h>
#include <sys/dirent.h>
#include <stdio.h>

main()
{
	register int i;
	register int num_entries;
	auto struct dirent **namelist;
	extern int alphasort();

	num_entries = scandir(".", &namelist, (int (*)())NULL, alphasort);
	for (i = 0; i < num_entries; i++)
		printf("%s\n", namelist[i]->d_name);
	exit(0);
}

John Bruner	Center for Supercomputing R&D, University of Illinois
	bruner at uicsrd.csrd.uiuc.edu	(217) 244-4476