git: 421025a274fb - main - access.2: Mention that lstat(2) should be used for symbolic links

From: Gordon Bergling <gbe_at_FreeBSD.org>
Date: Mon, 13 May 2024 08:40:33 UTC
The branch main has been updated by gbe:

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

commit 421025a274fb5759b3ecc8bdb30b24db830b45ae
Author:     Gordon Bergling <gbe@FreeBSD.org>
AuthorDate: 2024-05-13 08:40:12 +0000
Commit:     Gordon Bergling <gbe@FreeBSD.org>
CommitDate: 2024-05-13 08:40:12 +0000

    access.2: Mention that lstat(2) should be used for symbolic links
    
    access(), eaccess() and faccessat() will always dereference
    symbolic links.
    
    So add a note in the manual page, that lstat(2) should be
    used in the case of symbolic links.
    
    PR:     262895
    Reviewed by:    gbe, pauamma_gundo.com
    MFC after:      1 week
    Differential Revision:  https://reviews.freebsd.org/D44890
---
 lib/libsys/access.2 | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/lib/libsys/access.2 b/lib/libsys/access.2
index 1dab63afccde..91fe50a08cc4 100644
--- a/lib/libsys/access.2
+++ b/lib/libsys/access.2
@@ -25,7 +25,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd March 30, 2021
+.Dd May 13, 2024
 .Dt ACCESS 2
 .Os
 .Sh NAME
@@ -147,6 +147,15 @@ Likewise for
 .Dv R_OK
 and
 .Dv W_OK .
+.Pp
+.Fn access ,
+.Fn eaccess
+and
+.Fn faccessat
+will always dereference symbolic links.
+If the symbolic link itself needs to be referenced,
+.Xr lstat 2
+should be used instead.
 .Sh RETURN VALUES
 .Rv -std
 .Sh ERRORS