While RESOLVE_BENEATH was based on FreeBSD's O_BENEATH, there was a
well-known safety issue in O_BENEATH that we explicitly avoided
replicating -- FreeBSD would only verify whether the lookup escaped the
dirfd *at the end of the path lookup*.

This meant that even with O_BENEATH, an attacker could gain information
about the structure of the filesystem outside of the dirfd through
timing attacks or other side-channels.

Once Linux had RESOLVE_BENEATH, FreeBSD implemented O_RESOLVE_BENEATH to
mimic the same behaviour[1] and eventually removed O_BENEATH entirely
from their system[2]. It seems prudent to provide this epilogue in the
HISTORY section of the openat2(2) man page (the FreeBSD man page does
for open(2) not reference this historical connection with Linux at all,
as far as I can tell).

[1]: https://reviews.freebsd.org/D25886
[2]: https://reviews.freebsd.org/D28907

Signed-off-by: Aleksa Sarai <redacted>
---
 man/man2/openat2.2 | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/man/man2/openat2.2 b/man/man2/openat2.2
index e7d400920049..53687e676ae5 100644
--- a/man/man2/openat2.2
+++ b/man/man2/openat2.2

@@ -478,7 +478,20 @@ Linux 5.6.
 The semantics of
 .B RESOLVE_BENEATH
 were modeled after FreeBSD's
+.BR O_BENEATH ,
+but avoided a well-known correctness bug in FreeBSD's implementation that
+rendered it effectively insecure.
+Later, FreeBSD 13 introduced
+.BR O_RESOLVE_BENEATH
+to replace the insecure
 .BR O_BENEATH .
+.\" https://reviews.freebsd.org/D25886
+.\" https://reviews.freebsd.org/D28907
+FreeBSD's
+.BR O_RESOLVE_BENEATH
+semantics are based on Linux's
+.BR RESOLVE_BENEATH
+and the two are now functionally equivalent.
 .SH NOTES
 .SS Extensibility
 In order to allow for future extensibility,

---

base-commit: 5d53969e60c484673745ed47d6015a1f09c8641e
change-id: 20250721-openat2-history-2a8f71c9e3b0

Best regards,
-- 
Aleksa Sarai [off-list ref]