git: a294e679738b - main - Document scandirat(3)

The branch main has been updated by kib:

URL: https://cgit.FreeBSD.org/src/commit/?id=a294e679738bb4d2254c0ff416d40f6d6329754a

commit a294e679738bb4d2254c0ff416d40f6d6329754a
Author:     Konstantin Belousov <kib@FreeBSD.org>
AuthorDate: 2022-08-23 03:40:06 +0000
Commit:     Konstantin Belousov <kib@FreeBSD.org>
CommitDate: 2022-08-24 19:26:01 +0000

    Document scandirat(3)
    
    Reviewed by:    emaste, gbe (man pages), imp, kevans, markj, Aymeric Wibo <obiwac@gmail.com>
    Sponsored by:   The FreeBSD Foundation
    MFC after:      1 week
    Differential revision:  https://reviews.freebsd.org/D36301
---
 lib/libc/gen/Makefile.inc |  1 +
 lib/libc/gen/scandir.3    | 49 ++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 49 insertions(+), 1 deletion(-)

diff --git a/lib/libc/gen/Makefile.inc b/lib/libc/gen/Makefile.inc
index 161c061a1742..6d0e542a1f7b 100644
--- a/lib/libc/gen/Makefile.inc
+++ b/lib/libc/gen/Makefile.inc
@@ -494,6 +494,7 @@ MLINKS+=rand48.3 _rand48.3 \
 	rand48.3 srand48.3
 MLINKS+=recv.2 recvmmsg.2
 MLINKS+=scandir.3 alphasort.3 \
+	scandir.3 scandirat.3 \
 	scandir.3 scandir_b.3
 MLINKS+=sem_open.3 sem_close.3 \
 	sem_open.3 sem_unlink.3
diff --git a/lib/libc/gen/scandir.3 b/lib/libc/gen/scandir.3
index 47057fc647fc..b533b33ce7a7 100644
--- a/lib/libc/gen/scandir.3
+++ b/lib/libc/gen/scandir.3
@@ -28,11 +28,12 @@
 .\"     @(#)scandir.3	8.1 (Berkeley) 6/4/93
 .\" $FreeBSD$
 .\"
-.Dd January 3, 2010
+.Dd August 23, 2022
 .Dt SCANDIR 3
 .Os
 .Sh NAME
 .Nm scandir ,
+.Nm scandirat ,
 .Nm scandir_b ,
 .Nm alphasort
 .Nd scan a directory
@@ -47,6 +48,14 @@
 .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
 .Fo scandir_b
 .Fa "const char *dirname"
@@ -102,6 +111,39 @@ The memory allocated for the array can be deallocated with
 by freeing each pointer in the array and then the array itself.
 .Pp
 The
+.Fn scandirat
+function is similar to
+.Fn scandir ,
+but takes an additional
+.Fa dirfd
+argument.
+If the supplied
+.Fa dirname
+is absolute, the function's behavior is identical to that of
+.Fn scandir ,
+the
+.Fa dirfd
+argument is unused.
+If
+.Fa dirname
+is relative,
+.Fa dirfd
+must be a valid file descriptor referencing a directory, in
+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
 function behaves in the same way as
 .Fn scandir ,
@@ -114,6 +156,7 @@ 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 openat 2 ,
 .Xr directory 3 ,
 .Xr malloc 3 ,
 .Xr qsort 3 ,
@@ -126,3 +169,7 @@ and
 .Fn alphasort
 functions appeared in
 .Bx 4.2 .
+The
+.Fn scandirat
+function was added in
+.Fx 14.0 .