Changeset View
Changeset View
Standalone View
Standalone View
lib/libc/gen/scandir.3
Show All 22 Lines | |||||||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | ||||||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | ||||||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | ||||||||
.\" SUCH DAMAGE. | .\" SUCH DAMAGE. | ||||||||
.\" | .\" | ||||||||
.\" @(#)scandir.3 8.1 (Berkeley) 6/4/93 | .\" @(#)scandir.3 8.1 (Berkeley) 6/4/93 | ||||||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||||||
.\" | .\" | ||||||||
.Dd January 3, 2010 | .Dd August 23, 2022 | ||||||||
.Dt SCANDIR 3 | .Dt SCANDIR 3 | ||||||||
.Os | .Os | ||||||||
.Sh NAME | .Sh NAME | ||||||||
.Nm scandir , | .Nm scandir , | ||||||||
.Nm scandirat , | |||||||||
.Nm scandir_b , | |||||||||
obiwac_gmail.com: Shouldn't `scandirat` be added here too? | |||||||||
.Nm alphasort | .Nm alphasort | ||||||||
.Nd scan a directory | .Nd scan a directory | ||||||||
.Sh LIBRARY | .Sh LIBRARY | ||||||||
.Lb libc | .Lb libc | ||||||||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||||||||
.In dirent.h | .In dirent.h | ||||||||
.Ft int | .Ft int | ||||||||
.Fn scandir "const char *dirname" "struct dirent ***namelist" "int \*(lp*select\*(rp\*(lpconst struct dirent *\*(rp" "int \*(lp*compar\*(rp\*(lpconst struct dirent **, const struct dirent **\*(rp" | .Fo scandir | ||||||||
.Fa "const char *dirname" | |||||||||
.Fa "struct dirent ***namelist" | |||||||||
.Fa "int \*(lp*select\*(rp\*(lpconst struct dirent *\*(rp" | |||||||||
.Fa "int \*(lp*compar\*(rp\*(lpconst struct dirent **, const struct dirent **\*(rp" | |||||||||
.Fc | |||||||||
.Ft | |||||||||
.Fo scandirat | |||||||||
.Fa int dirfd | |||||||||
.Fa "const char *dirname" | |||||||||
.Fa "struct dirent ***namelist" | |||||||||
.Fa "int \*(lp*select\*(rp\*(lpconst struct dirent *\*(rp" | |||||||||
.Fa "int \*(lp*compar\*(rp\*(lpconst struct dirent **, const struct dirent **\*(rp" | |||||||||
.Fc | |||||||||
.Ft int | .Ft int | ||||||||
.Fn scandir_b "const char *dirname" "struct dirent ***namelist" "int \*(lp*select\^(rp\*(lpconst struct dirent *\*(rp" "int \*(lp^compar\*(rp\*(lpconst struct dirent **, const struct dirent **\*(rp" | .Fo scandir_b | ||||||||
.Fa "const char *dirname" | |||||||||
.Fa "struct dirent ***namelist" | |||||||||
.Fa "int \*(lp*select\^(rp\*(lpconst struct dirent *\*(rp" | |||||||||
.Fa "int \*(lp^compar\*(rp\*(lpconst struct dirent **, const struct dirent **\*(rp" | |||||||||
.Fc | |||||||||
.Ft int | .Ft int | ||||||||
.Fn alphasort "const struct dirent **d1" "const struct dirent **d2" | .Fn alphasort "const struct dirent **d1" "const struct dirent **d2" | ||||||||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||||||||
The | The | ||||||||
.Fn scandir | .Fn scandir | ||||||||
function | function | ||||||||
reads the directory | reads the directory | ||||||||
.Fa dirname | .Fa dirname | ||||||||
Show All 32 Lines | |||||||||
argument to sort the array alphabetically using | argument to sort the array alphabetically using | ||||||||
.Xr strcoll 3 . | .Xr strcoll 3 . | ||||||||
.Pp | .Pp | ||||||||
The memory allocated for the array can be deallocated with | The memory allocated for the array can be deallocated with | ||||||||
.Xr free 3 , | .Xr free 3 , | ||||||||
by freeing each pointer in the array and then the array itself. | by freeing each pointer in the array and then the array itself. | ||||||||
.Pp | .Pp | ||||||||
The | The | ||||||||
.Fn scandirat | |||||||||
function is similar to | |||||||||
.Fn scandir , | |||||||||
but takes an additional | |||||||||
Done Inline ActionsMissing "an" ("takes an additional dirfd argument")? obiwac_gmail.com: Missing "an" ("takes //an// additional `dirfd` argument")? | |||||||||
.Fa dirfd | |||||||||
argument. | |||||||||
If the supplied | |||||||||
.Fa dirname | |||||||||
is absolute, the function's behavior is identical to that of | |||||||||
Done Inline Actions
markj: | |||||||||
.Fn scandir , | |||||||||
the | |||||||||
Done Inline Actions
obiwac_gmail.com: | |||||||||
.Fa dirfd | |||||||||
argument is unused. | |||||||||
If | |||||||||
.Fa dirname | |||||||||
Not Done Inline ActionsThe wording implies that in the case where dirname is absolute, dirfd may be invalid. But, that's not true right? So in the description of the absolute case, perhaps add, "The .Fa dirfd argument is unused, but must be a valid file descriptor or the special value .Dv AT_FDCWD." markj: The wording implies that in the case where dirname is absolute, dirfd may be invalid. But… | |||||||||
Done Inline ActionsHm, I thought that dirfd can be invalid. And both from my reading of namei_setup(), and actual testing, dirfd is ignored when first character of path is '/': openat(-10000004,"/etc/passwd",O_RDONLY,00) = 3 (0x3) kib: Hm, I thought that dirfd can be invalid. And both from my reading of namei_setup(), and actual… | |||||||||
Not Done Inline ActionsOops, sorry. I looked at namei() before writing the comment, but misread. markj: Oops, sorry. I looked at namei() before writing the comment, but misread. | |||||||||
is relative, | |||||||||
.Fa dirfd | |||||||||
must be a valid file descriptor referencing a directory, in | |||||||||
Done Inline Actions
markj: | |||||||||
which case the | |||||||||
.Fa dirname | |||||||||
lookup is performed relative to the directory referenced by | |||||||||
.Fa dirfd . | |||||||||
If | |||||||||
.Fa dirfd | |||||||||
has the special value | |||||||||
.Va AT_FDCWD , | |||||||||
then the current process directory is used as the base for | |||||||||
relative lookups. | |||||||||
See | |||||||||
.Xr openat 2 | |||||||||
for additional details. | |||||||||
.Pp | |||||||||
The | |||||||||
.Fn scandir_b | .Fn scandir_b | ||||||||
function behaves in the same way as | function behaves in the same way as | ||||||||
.Fn scandir , | .Fn scandir , | ||||||||
but takes blocks as arguments instead of function pointers and calls | but takes blocks as arguments instead of function pointers and calls | ||||||||
.Fn qsort_b | .Fn qsort_b | ||||||||
rather than | rather than | ||||||||
.Fn qsort . | .Fn qsort . | ||||||||
.Sh DIAGNOSTICS | .Sh DIAGNOSTICS | ||||||||
Returns \-1 if the directory cannot be opened for reading or if | Returns \-1 if the directory cannot be opened for reading or if | ||||||||
.Xr malloc 3 | .Xr malloc 3 | ||||||||
cannot allocate enough memory to hold all the data structures. | cannot allocate enough memory to hold all the data structures. | ||||||||
.Sh SEE ALSO | .Sh SEE ALSO | ||||||||
.Xr openat 2 , | |||||||||
.Xr directory 3 , | .Xr directory 3 , | ||||||||
.Xr malloc 3 , | .Xr malloc 3 , | ||||||||
.Xr qsort 3 , | .Xr qsort 3 , | ||||||||
.Xr strcoll 3 , | .Xr strcoll 3 , | ||||||||
.Xr dir 5 | .Xr dir 5 | ||||||||
.Sh HISTORY | .Sh HISTORY | ||||||||
The | The | ||||||||
.Fn scandir | .Fn scandir | ||||||||
and | and | ||||||||
.Fn alphasort | .Fn alphasort | ||||||||
functions appeared in | functions appeared in | ||||||||
.Bx 4.2 . | .Bx 4.2 . | ||||||||
The | |||||||||
.Fn scandirat | |||||||||
function was added in | |||||||||
.Fx 14.0 . |
Shouldn't scandirat be added here too?