sync with OpenBSD -current

lib/libc/gen/scandir.3

@@ -1,4 +1,4 @@
-.\"	$OpenBSD: scandir.3,v 1.16 2021/06/17 18:18:15 jmc Exp $
+.\"	$OpenBSD: scandir.3,v 1.17 2024/04/15 15:47:58 florian Exp $
 .\"
 .\" Copyright (c) 1983, 1991, 1993
 .\"	The Regents of the University of California.  All rights reserved.
@@ -27,11 +27,12 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: June 17 2021 $
+.Dd $Mdocdate: April 15 2024 $
 .Dt SCANDIR 3
 .Os
 .Sh NAME
 .Nm scandir ,
+.Nm scandirat ,
 .Nm alphasort
 .Nd scan a directory
 .Sh SYNOPSIS
@@ -45,6 +46,14 @@
 .Fa "int (*compar)(const struct dirent **, const struct dirent **)"
 .Fc
 .Ft int
+.Fo scandirat
+.Fa "int dirfd"
+.Fa "const char *dirname"
+.Fa "struct dirent ***namelist"
+.Fa "int (*select)(const struct dirent *)"
+.Fa "int (*compar)(const struct dirent **, const struct dirent **)"
+.Fc
+.Ft int
 .Fn alphasort "const struct dirent **d1" "const struct dirent **d2"
 .Sh DESCRIPTION
 The
@@ -91,6 +100,30 @@ parameter to sort the array alphabetically.
 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.
+.Pp
+The
+.Fn scandirat
+function is similar to
+.Fn scandir ,
+but takes an additional
+.Fa dirfd
+argument.
+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.
 .Sh DIAGNOSTICS
 Returns \-1 if the directory cannot be opened for reading or if
 .Xr malloc 3