[unix-history] / usr / src / lib / libc / gen / scandir.3

.\" Copyright (c) 1983, 1991 Regents of the University of California.
.\" All rights reserved.
.\"
.\" %sccs.include.redist.man%
.\"
.\"     @(#)scandir.3	6.8 (Berkeley) %G%
.\"
.Dd 
.Dt SCANDIR 3
.Os BSD 4.2
.Sh NAME
.Nm scandir ,
.Nm alphasort
.Nd scan a directory
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <dirent.h>
.Ft int
.Fn scandir "const char *dirname" "struct dirent ***namelist" "int \\*(lp*select\\*(rp\\*(lpstruct dirent *\\*(rp" "int \\*(lp*compar\\*(rp\\*(lpconst void *, const void *\\*(rp"
.Ft int
.Fn alphasort "const void *d1" "const void *d2"
.Sh DESCRIPTION
The
.Fn scandir
function
reads the directory
.Fa dirname
and builds an array of pointers to directory
entries using
.Xr malloc 3 .
It returns the number of entries in the array.
A pointer to the array of directory entries is stored in the location
referenced by
.Fa namelist .
.Pp
The
.Fa select
parameter is a pointer to a user supplied subroutine which is called by
.Fn scandir
to select which entries are to be included in the array.
The select routine is passed a
pointer to a directory entry and should return a non-zero
value if the directory entry is to be included in the array.
If
.Fa select
is null, then all the directory entries will be included.
.Pp
The
.Fa compar
parameter is a pointer to a user supplied subroutine which is passed to
.Xr qsort 3
to sort the completed array.
If this pointer is null, the array is not sorted.
.Pp
The
.Fn alphasort
function
is a routine which can be used for the
.Fa compar
parameter to sort the array alphabetically.
.Pp
The memory allocated for the array can be deallocated with
.Xr free 3 ,
by freeing each pointer in the array and then the array itself.
.Sh DIAGNOSTICS
Returns \-1 if the directory cannot be opened for reading or if
.Xr malloc 3
cannot allocate enough memory to hold all the data structures.
.Sh SEE ALSO
.Xr directory 3 ,
.Xr malloc 3 ,
.Xr qsort 3 ,
.Xr dir 5
.Sh HISTORY
The
.Fn scandir
and
.Fn alphasort
functions appeared in 
.Bx 4.2 .
Commit	Line	Data
ae59e04c	1	.\" Copyright (c) 1983, 1991 Regents of the University of California.
25aac6e1	2	.\" All rights reserved.
460316d1	3	.\"
91cff1e1	4	.\" %sccs.include.redist.man%
25aac6e1	5	.\"
ae59e04c	6	.\" @(#)scandir.3 6.8 (Berkeley) %G%
460316d1	7	.\"
ae59e04c CL	8	.Dd
	9	.Dt SCANDIR 3
	10	.Os BSD 4.2
	11	.Sh NAME
	12	.Nm scandir ,
	13	.Nm alphasort
	14	.Nd scan a directory
	15	.Sh SYNOPSIS
	16	.Fd #include <sys/types.h>
	17	.Fd #include <dirent.h>
	18	.Ft int
	19	.Fn scandir "const char dirname" "struct dirent *namelist" "int \\(lpselect\\(rp\\(lpstruct dirent \\(rp" "int \\(lpcompar\\(rp\\(lpconst void , const void \\(rp"
	20	.Ft int
	21	.Fn alphasort "const void d1" "const void d2"
	22	.Sh DESCRIPTION
	23	The
	24	.Fn scandir
	25	function
460316d1	26	reads the directory
ae59e04c	27	.Fa dirname
460316d1 KM	28	and builds an array of pointers to directory
460316d1 KM	29	entries using
ae59e04c	30	.Xr malloc 3 .
4754ea9c KB	31	It returns the number of entries in the array.
	32	A pointer to the array of directory entries is stored in the location
	33	referenced by
ae59e04c CL	34	.Fa namelist .
ae59e04c CL	35	.Pp
460316d1	36	The
ae59e04c	37	.Fa select
460316d1	38	parameter is a pointer to a user supplied subroutine which is called by
ae59e04c	39	.Fn scandir
460316d1 KM	40	to select which entries are to be included in the array.
	41	The select routine is passed a
	42	pointer to a directory entry and should return a non-zero
	43	value if the directory entry is to be included in the array.
	44	If
ae59e04c	45	.Fa select
460316d1	46	is null, then all the directory entries will be included.
ae59e04c	47	.Pp
460316d1	48	The
ae59e04c	49	.Fa compar
460316d1	50	parameter is a pointer to a user supplied subroutine which is passed to
ae59e04c	51	.Xr qsort 3
643c10cf KB	52	to sort the completed array.
643c10cf KB	53	If this pointer is null, the array is not sorted.
ae59e04c CL	54	.Pp
	55	The
	56	.Fn alphasort
	57	function
460316d1	58	is a routine which can be used for the
ae59e04c	59	.Fa compar
460316d1	60	parameter to sort the array alphabetically.
ae59e04c	61	.Pp
460316d1	62	The memory allocated for the array can be deallocated with
ae59e04c	63	.Xr free 3 ,
643c10cf	64	by freeing each pointer in the array and then the array itself.
ae59e04c	65	.Sh DIAGNOSTICS
460316d1	66	Returns \-1 if the directory cannot be opened for reading or if
ae59e04c	67	.Xr malloc 3
460316d1	68	cannot allocate enough memory to hold all the data structures.
ae59e04c CL	69	.Sh SEE ALSO
	70	.Xr directory 3 ,
	71	.Xr malloc 3 ,
	72	.Xr qsort 3 ,
	73	.Xr dir 5
	74	.Sh HISTORY
	75	The
	76	.Fn scandir
	77	and
	78	.Fn alphasort
	79	functions appeared in
	80	.Bx 4.2 .