git: a7593bf87d54 - stable/13 - Document scandirat(3)

The branch stable/13 has been updated by kib:

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

commit a7593bf87d54bb7d6c7224264bf507b1b41efcc7
Author:     Konstantin Belousov <kib@FreeBSD.org>
AuthorDate: 2022-08-23 03:40:06 +0000
Commit:     Konstantin Belousov <kib@FreeBSD.org>
CommitDate: 2022-08-31 01:20:28 +0000

    Document scandirat(3)
    
    (cherry picked from commit a294e679738bb4d2254c0ff416d40f6d6329754a)
---
 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 616390ea8559..a8037564a095 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 .