Path: utzoo!utgpu!attcan!uunet!wuarchive!husc6!rice!sun-spots-request
From: bruner@uicsrd.csrd.uiuc.edu (John Bruner)
Newsgroups: comp.sys.sun
Subject: scandir(3) manual page wrong
Keywords: SunOS
Message-ID: <1851@brazos.Rice.edu>
Date: 28 Sep 89 16:53:14 GMT
Sender: root@rice.edu
Organization: Sun-Spots
Lines: 40
Approved: Sun-Spots@rice.edu
X-Sun-Spots-Digest: Volume 8, Issue 148, message 9 of 10

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  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 
#include 
#include 

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@uicsrd.csrd.uiuc.edu	(217) 244-4476