sync with OpenBSD -current

lib/libc/sys/pathconf.2

@@ -1,4 +1,4 @@
-.\"	$OpenBSD: pathconf.2,v 1.25 2018/06/21 20:30:36 jmc Exp $
+.\"	$OpenBSD: pathconf.2,v 1.26 2024/05/18 05:20:22 guenther Exp $
 .\"	$NetBSD: pathconf.2,v 1.2 1995/02/27 12:35:22 cgd Exp $
 .\"
 .\" Copyright (c) 1993
@@ -30,11 +30,12 @@
 .\"
 .\"	@(#)pathconf.2	8.1 (Berkeley) 6/4/93
 .\"
-.Dd $Mdocdate: June 21 2018 $
+.Dd $Mdocdate: May 18 2024 $
 .Dt PATHCONF 2
 .Os
 .Sh NAME
 .Nm pathconf ,
+.Nm pathconfat ,
 .Nm fpathconf
 .Nd get configurable pathname variables
 .Sh SYNOPSIS
@@ -43,9 +44,13 @@
 .Fn pathconf "const char *path" "int name"
 .Ft long
 .Fn fpathconf "int fd" "int name"
+.In fcntl.h
+.Ft long
+.Fn pathconfat "int fd" "const char *path" "int name" "int flag"
 .Sh DESCRIPTION
 The
-.Fn pathconf
+.Fn pathconf ,
+.Fn pathconfat ,
 and
 .Fn fpathconf
 functions provide a method for applications to determine the current
@@ -132,9 +137,48 @@ Returns 1 if synchronized I/O is supported, otherwise 0.
 .It Dv _PC_TIMESTAMP_RESOLUTION
 The resolution in nanoseconds of file timestamps.
 .El
+.Pp
+The
+.Fn pathconfat
+function is equivalent to
+.Fn pathconf
+except in the case where
+.Fa path
+specifies a relative path.
+In this case the file to be changed is determined relative to the directory
+associated with the file descriptor
+.Fa fd
+instead of the current working directory.
+.Pp
+If
+.Fn pathconfat
+is passed the special value
+.Dv AT_FDCWD
+(defined in
+.In fcntl.h )
+in the
+.Fa fd
+parameter, the current working directory is used.
+If
+.Fa flag
+is also zero, the behavior is identical to a call to
+.Fn pathconf .
+.Pp
+The
+.Fa flag
+argument is the bitwise OR of zero or more of the following values:
+.Pp
+.Bl -tag -width AT_SYMLINK_NOFOLLOW -offset indent -compact
+.It Dv AT_SYMLINK_NOFOLLOW
+If
+.Fa path
+names a symbolic link, then the system variable for the symbolic
+link is queried.
+.El
 .Sh RETURN VALUES
 If the call to
-.Fn pathconf
+.Fn pathconf ,
+.Fn pathconfat ,
 or
 .Fn fpathconf
 is not successful, \-1 is returned and
@@ -147,7 +191,8 @@ is not modified.
 Otherwise, the current variable value is returned.
 .Sh ERRORS
 If any of the following conditions occur, the
-.Fn pathconf
+.Fn pathconf ,
+.Fn pathconfat ,
 and
 .Fn fpathconf
 functions shall return \-1 and set
@@ -166,6 +211,8 @@ An I/O error occurred while reading from the file system.
 .El
 .Pp
 .Fn pathconf
+and
+.Fn pathconfat
 will fail if:
 .Bl -tag -width Er
 .It Bq Er ENOTDIR
@@ -190,6 +237,38 @@ Too many symbolic links were encountered in translating the pathname.
 points outside the process's allocated address space.
 .El
 .Pp
+Additionally, the
+.Fn pathconfat
+function will fail if:
+.Bl -tag -width Er
+.It Bq Er EINVAL
+The value of the
+.Fa flag
+argument was neither zero nor
+.Dv AT_SYMLINK_NOFOLLOW .
+.It Bq Er EBADF
+The
+.Fa path
+argument specifies a relative path and the
+.Fa fd
+argument is neither
+.Dv AT_FDCWD
+nor a valid file descriptor.
+.It Bq Er ENOTDIR
+The
+.Fa path
+argument specifies a relative path and the
+.Fa fd
+argument is a valid file descriptor but it does not reference a directory.
+.It Bq Er EACCES
+The
+.Fa path
+argument specifies a relative path but search permission is denied
+for the directory which the
+.Fa fd
+file descriptor references.
+.El
+.Pp
 .Fn fpathconf
 will fail if:
 .Bl -tag -width Er
@@ -214,3 +293,7 @@ and
 .Fn fpathconf
 functions first appeared in
 .Bx 4.4 .
+The
+.Fn pathconfat
+function first appeared in
+.Ox 7.6 .