25 files changed, 326 insertions, 111 deletions

diff --git a/lib/libc/locale/cXXrtomb_iconv.h b/lib/libc/locale/cXXrtomb_iconv.h
index d0dadac6c3121..1f87e353e0522 100644
--- a/lib/libc/locale/cXXrtomb_iconv.h
+++ b/lib/libc/locale/cXXrtomb_iconv.h
@@ -39,7 +39,7 @@ __FBSDID("$FreeBSD$");
 #include "../iconv/citrus_hash.h"
 #include "../iconv/citrus_module.h"
 #include "../iconv/citrus_iconv.h"
-#include "xlocale_private.h"
+#include "mblocal.h"
 
 typedef struct {
 	bool			initialized;
@@ -65,7 +65,7 @@ cXXrtomb_l(char * __restrict s, charXX_t c, mbstate_t * __restrict ps,
 
 	FIX_LOCALE(locale);
 	if (ps == NULL)
-		ps = &locale->cXXrtomb;
+		ps = &(XLOCALE_CTYPE(locale)->cXXrtomb);
 	cs = (_ConversionState *)ps;
 	handle = &cs->iconv;
 
diff --git a/lib/libc/locale/mblen.c b/lib/libc/locale/mblen.c
index e972298f5b404..77d9745da1981 100644
--- a/lib/libc/locale/mblen.c
+++ b/lib/libc/locale/mblen.c
@@ -47,10 +47,11 @@ mblen_l(const char *s, size_t n, locale_t locale)
 
 	if (s == NULL) {
 		/* No support for state dependent encodings. */
-		locale->mblen = initial;
+		XLOCALE_CTYPE(locale)->mblen = initial;
 		return (0);
 	}
-	rval = XLOCALE_CTYPE(locale)->__mbrtowc(NULL, s, n, &locale->mblen);
+	rval = XLOCALE_CTYPE(locale)->__mbrtowc(NULL, s, n,
+	    &(XLOCALE_CTYPE(locale)->mblen));
 	if (rval == (size_t)-1 || rval == (size_t)-2)
 		return (-1);
 	return ((int)rval);
diff --git a/lib/libc/locale/mblocal.h b/lib/libc/locale/mblocal.h
index cffe3ba92bc8e..1fb5902a8d115 100644
--- a/lib/libc/locale/mblocal.h
+++ b/lib/libc/locale/mblocal.h
@@ -60,6 +60,34 @@ struct xlocale_ctype {
 		size_t, size_t, mbstate_t * __restrict);
 	int __mb_cur_max;
 	int __mb_sb_limit;
+	/** Persistent state used by mblen() calls. */
+	__mbstate_t mblen;
+	/** Persistent state used by mbrlen() calls. */
+	__mbstate_t mbrlen;
+	/** Persistent state used by mbrtoc16() calls. */
+	__mbstate_t mbrtoc16;
+	/** Persistent state used by mbrtoc32() calls. */
+	__mbstate_t mbrtoc32;
+	/** Persistent state used by mbrtowc() calls. */
+	__mbstate_t mbrtowc;
+	/** Persistent state used by mbsnrtowcs() calls. */
+	__mbstate_t mbsnrtowcs;
+	/** Persistent state used by mbsrtowcs() calls. */
+	__mbstate_t mbsrtowcs;
+	/** Persistent state used by mbtowc() calls. */
+	__mbstate_t mbtowc;
+	/** Persistent state used by c16rtomb() calls. */
+	__mbstate_t c16rtomb;
+	/** Persistent state used by c32rtomb() calls. */
+	__mbstate_t c32rtomb;
+	/** Persistent state used by wcrtomb() calls. */
+	__mbstate_t wcrtomb;
+	/** Persistent state used by wcsnrtombs() calls. */
+	__mbstate_t wcsnrtombs;
+	/** Persistent state used by wcsrtombs() calls. */
+	__mbstate_t wcsrtombs;
+	/** Persistent state used by wctomb() calls. */
+	__mbstate_t wctomb;
 };
 #define XLOCALE_CTYPE(x) ((struct xlocale_ctype*)(x)->components[XLC_CTYPE])
 extern struct xlocale_ctype __xlocale_global_ctype;
diff --git a/lib/libc/locale/mbrlen.c b/lib/libc/locale/mbrlen.c
index f84fce7b61b0a..4f687e98628f1 100644
--- a/lib/libc/locale/mbrlen.c
+++ b/lib/libc/locale/mbrlen.c
@@ -42,7 +42,7 @@ mbrlen_l(const char * __restrict s, size_t n, mbstate_t * __restrict ps, locale_
 {
 	FIX_LOCALE(locale);
 	if (ps == NULL)
-		ps = &locale->mbrlen;
+		ps = &(XLOCALE_CTYPE(locale)->mbrlen);
 	return (XLOCALE_CTYPE(locale)->__mbrtowc(NULL, s, n, ps));
 }
 
diff --git a/lib/libc/locale/mbrtocXX_iconv.h b/lib/libc/locale/mbrtocXX_iconv.h
index 262818ee79d56..d753b3523244b 100644
--- a/lib/libc/locale/mbrtocXX_iconv.h
+++ b/lib/libc/locale/mbrtocXX_iconv.h
@@ -41,7 +41,7 @@ __FBSDID("$FreeBSD$");
 #include "../iconv/citrus_hash.h"
 #include "../iconv/citrus_module.h"
 #include "../iconv/citrus_iconv.h"
-#include "xlocale_private.h"
+#include "mblocal.h"
 
 typedef struct {
 	bool			initialized;
@@ -68,7 +68,7 @@ mbrtocXX_l(charXX_t * __restrict pc, const char * __restrict s, size_t n,
 
 	FIX_LOCALE(locale);
 	if (ps == NULL)
-		ps = &locale->mbrtocXX;
+		ps = &(XLOCALE_CTYPE(locale)->mbrtocXX);
 	cs = (_ConversionState *)ps;
 	handle = &cs->iconv;
 
diff --git a/lib/libc/locale/mbrtowc.c b/lib/libc/locale/mbrtowc.c
index 4171886c8efa0..7585ef16bca2c 100644
--- a/lib/libc/locale/mbrtowc.c
+++ b/lib/libc/locale/mbrtowc.c
@@ -43,7 +43,7 @@ mbrtowc_l(wchar_t * __restrict pwc, const char * __restrict s,
 {
 	FIX_LOCALE(locale);
 	if (ps == NULL)
-		ps = &locale->mbrtowc;
+		ps = &(XLOCALE_CTYPE(locale)->mbrtowc);
 	return (XLOCALE_CTYPE(locale)->__mbrtowc(pwc, s, n, ps));
 }
 
diff --git a/lib/libc/locale/mbsnrtowcs.c b/lib/libc/locale/mbsnrtowcs.c
index 59574386b0afb..69e48eafdc573 100644
--- a/lib/libc/locale/mbsnrtowcs.c
+++ b/lib/libc/locale/mbsnrtowcs.c
@@ -48,7 +48,7 @@ mbsnrtowcs_l(wchar_t * __restrict dst, const char ** __restrict src,
 {
 	FIX_LOCALE(locale);
 	if (ps == NULL)
-		ps = &locale->mbsnrtowcs;
+		ps = &(XLOCALE_CTYPE(locale)->mbsnrtowcs);
 	return (XLOCALE_CTYPE(locale)->__mbsnrtowcs(dst, src, nms, len, ps));
 }
 size_t
diff --git a/lib/libc/locale/mbsrtowcs.c b/lib/libc/locale/mbsrtowcs.c
index aefbee1c2d09d..e85b22b492bf4 100644
--- a/lib/libc/locale/mbsrtowcs.c
+++ b/lib/libc/locale/mbsrtowcs.c
@@ -46,7 +46,7 @@ mbsrtowcs_l(wchar_t * __restrict dst, const char ** __restrict src, size_t len,
 {
 	FIX_LOCALE(locale);
 	if (ps == NULL)
-		ps = &locale->mbsrtowcs;
+		ps = &(XLOCALE_CTYPE(locale)->mbsrtowcs);
 	return (XLOCALE_CTYPE(locale)->__mbsnrtowcs(dst, src, SIZE_T_MAX, len, ps));
 }
 size_t
diff --git a/lib/libc/locale/mbtowc.c b/lib/libc/locale/mbtowc.c
index df1b204187e92..ec634807560d6 100644
--- a/lib/libc/locale/mbtowc.c
+++ b/lib/libc/locale/mbtowc.c
@@ -48,10 +48,11 @@ mbtowc_l(wchar_t * __restrict pwc, const char * __restrict s, size_t n, locale_t
 
 	if (s == NULL) {
 		/* No support for state dependent encodings. */
-		locale->mbtowc = initial;
+		XLOCALE_CTYPE(locale)->mbtowc = initial;
 		return (0);
 	}
-	rval = XLOCALE_CTYPE(locale)->__mbrtowc(pwc, s, n, &locale->mbtowc);
+	rval = XLOCALE_CTYPE(locale)->__mbrtowc(pwc, s, n,
+	    &(XLOCALE_CTYPE(locale)->mbtowc));
 	switch (rval) {
 	case (size_t)-2:
 		errno = EILSEQ;
diff --git a/lib/libc/locale/setrunelocale.c b/lib/libc/locale/setrunelocale.c
index 97af903f27242..2e6fed9466e43 100644
--- a/lib/libc/locale/setrunelocale.c
+++ b/lib/libc/locale/setrunelocale.c
@@ -160,6 +160,21 @@ __setrunelocale(struct xlocale_ctype *l, const char *encoding)
 	if (ret == 0) {
 		/* Free the old runes if it exists. */
 		free_runes(saved.runes);
+		/* Reset the mbstates */
+		memset(&l->c16rtomb, 0, sizeof(l->c16rtomb));
+		memset(&l->c32rtomb, 0, sizeof(l->c32rtomb));
+		memset(&l->mblen, 0, sizeof(l->mblen));
+		memset(&l->mbrlen, 0, sizeof(l->mbrlen));
+		memset(&l->mbrtoc16, 0, sizeof(l->mbrtoc16));
+		memset(&l->mbrtoc32, 0, sizeof(l->mbrtoc32));
+		memset(&l->mbrtowc, 0, sizeof(l->mbrtowc));
+		memset(&l->mbsnrtowcs, 0, sizeof(l->mbsnrtowcs));
+		memset(&l->mbsrtowcs, 0, sizeof(l->mbsrtowcs));
+		memset(&l->mbtowc, 0, sizeof(l->mbtowc));
+		memset(&l->wcrtomb, 0, sizeof(l->wcrtomb));
+		memset(&l->wcsnrtombs, 0, sizeof(l->wcsnrtombs));
+		memset(&l->wcsrtombs, 0, sizeof(l->wcsrtombs));
+		memset(&l->wctomb, 0, sizeof(l->wctomb));
 	} else {
 		/* Restore the saved version if this failed. */
 		memcpy(l, &saved, sizeof(struct xlocale_ctype));
diff --git a/lib/libc/locale/wcrtomb.c b/lib/libc/locale/wcrtomb.c
index 1afa8f77acc98..fa5c08474475a 100644
--- a/lib/libc/locale/wcrtomb.c
+++ b/lib/libc/locale/wcrtomb.c
@@ -43,7 +43,7 @@ wcrtomb_l(char * __restrict s, wchar_t wc, mbstate_t * __restrict ps,
 {
 	FIX_LOCALE(locale);
 	if (ps == NULL)
-		ps = &locale->wcrtomb;
+		ps = &(XLOCALE_CTYPE(locale)->wcrtomb);
 	return (XLOCALE_CTYPE(locale)->__wcrtomb(s, wc, ps));
 }
 
diff --git a/lib/libc/locale/wcsnrtombs.c b/lib/libc/locale/wcsnrtombs.c
index 8d90445aacf16..7fdbfc75156df 100644
--- a/lib/libc/locale/wcsnrtombs.c
+++ b/lib/libc/locale/wcsnrtombs.c
@@ -48,7 +48,7 @@ wcsnrtombs_l(char * __restrict dst, const wchar_t ** __restrict src, size_t nwc,
 {
 	FIX_LOCALE(locale);
 	if (ps == NULL)
-		ps = &locale->wcsnrtombs;
+		ps = &(XLOCALE_CTYPE(locale)->wcsnrtombs);
 	return (XLOCALE_CTYPE(locale)->__wcsnrtombs(dst, src, nwc, len, ps));
 }
 size_t
diff --git a/lib/libc/locale/wcsrtombs.c b/lib/libc/locale/wcsrtombs.c
index ca9875799a3de..1466eab7046d6 100644
--- a/lib/libc/locale/wcsrtombs.c
+++ b/lib/libc/locale/wcsrtombs.c
@@ -46,7 +46,7 @@ wcsrtombs_l(char * __restrict dst, const wchar_t ** __restrict src, size_t len,
 {
 	FIX_LOCALE(locale);
 	if (ps == NULL)
-		ps = &locale->wcsrtombs;
+		ps = &(XLOCALE_CTYPE(locale)->wcsrtombs);
 	return (XLOCALE_CTYPE(locale)->__wcsnrtombs(dst, src, SIZE_T_MAX, len, ps));
 }
 
diff --git a/lib/libc/locale/wctomb.c b/lib/libc/locale/wctomb.c
index 151d67997548d..820021a3e0ab0 100644
--- a/lib/libc/locale/wctomb.c
+++ b/lib/libc/locale/wctomb.c
@@ -47,10 +47,11 @@ wctomb_l(char *s, wchar_t wchar, locale_t locale)
 
 	if (s == NULL) {
 		/* No support for state dependent encodings. */
-		locale->wctomb = initial;
+		XLOCALE_CTYPE(locale)->wctomb = initial;
 		return (0);
 	}
-	if ((rval = XLOCALE_CTYPE(locale)->__wcrtomb(s, wchar, &locale->wctomb)) == (size_t)-1)
+	if ((rval = XLOCALE_CTYPE(locale)->__wcrtomb(s, wchar,
+	    &(XLOCALE_CTYPE(locale)->wctomb))) == (size_t)-1)
 		return (-1);
 	return ((int)rval);
 }
diff --git a/lib/libc/locale/xlocale_private.h b/lib/libc/locale/xlocale_private.h
index 9aa4d86c87caf..fc04c9dd43a3d 100644
--- a/lib/libc/locale/xlocale_private.h
+++ b/lib/libc/locale/xlocale_private.h
@@ -128,34 +128,6 @@ struct _xlocale {
 	int using_messages_locale;
 	/** The structure to be returned from localeconv_l() for this locale. */
 	struct lconv lconv;
-	/** Persistent state used by mblen() calls. */
-	__mbstate_t mblen;
-	/** Persistent state used by mbrlen() calls. */
-	__mbstate_t mbrlen;
-	/** Persistent state used by mbrtoc16() calls. */
-	__mbstate_t mbrtoc16;
-	/** Persistent state used by mbrtoc32() calls. */
-	__mbstate_t mbrtoc32;
-	/** Persistent state used by mbrtowc() calls. */
-	__mbstate_t mbrtowc;
-	/** Persistent state used by mbsnrtowcs() calls. */
-	__mbstate_t mbsnrtowcs;
-	/** Persistent state used by mbsrtowcs() calls. */
-	__mbstate_t mbsrtowcs;
-	/** Persistent state used by mbtowc() calls. */
-	__mbstate_t mbtowc;
-	/** Persistent state used by c16rtomb() calls. */
-	__mbstate_t c16rtomb;
-	/** Persistent state used by c32rtomb() calls. */
-	__mbstate_t c32rtomb;
-	/** Persistent state used by wcrtomb() calls. */
-	__mbstate_t wcrtomb;
-	/** Persistent state used by wcsnrtombs() calls. */
-	__mbstate_t wcsnrtombs;
-	/** Persistent state used by wcsrtombs() calls. */
-	__mbstate_t wcsrtombs;
-	/** Persistent state used by wctomb() calls. */
-	__mbstate_t wctomb;
 	/** Buffer used by nl_langinfo_l() */
 	char *csym;
 };
diff --git a/lib/libc/net/nsdispatch.c b/lib/libc/net/nsdispatch.c
index b9533bd1ca46d..b0f80d079b0b3 100644
--- a/lib/libc/net/nsdispatch.c
+++ b/lib/libc/net/nsdispatch.c
@@ -335,6 +335,7 @@ static int
 nss_configure(void)
 {
 	static time_t	 confmod;
+	static int	 already_initialized = 0;
 	struct stat	 statbuf;
 	int		 result, isthreaded;
 	const char	*path;
@@ -352,6 +353,16 @@ nss_configure(void)
 	if (path == NULL)
 #endif
 		path = _PATH_NS_CONF;
+#ifndef NS_REREAD_CONF
+	/*
+	 * Define NS_REREAD_CONF to have nsswitch notice changes
+	 * to nsswitch.conf(5) during runtime.  This involves calling
+	 * stat(2) every time, which can result in performance hit.
+	 */
+	if (already_initialized)
+		return (0);
+	already_initialized = 1;
+#endif /* NS_REREAD_CONF */
 	if (stat(path, &statbuf) != 0)
 		return (0);
 	if (statbuf.st_mtime <= confmod)
diff --git a/lib/libc/sys/access.2 b/lib/libc/sys/access.2
index b1b049925c7d6..0001d99941b6e 100644
--- a/lib/libc/sys/access.2
+++ b/lib/libc/sys/access.2
@@ -28,7 +28,7 @@
 .\"     @(#)access.2	8.2 (Berkeley) 4/1/94
 .\" $FreeBSD$
 .\"
-.Dd October 20, 2018
+.Dd November 11, 2018
 .Dt ACCESS 2
 .Os
 .Sh NAME
@@ -121,7 +121,12 @@ The checks for accessibility are performed using the effective user and group
 IDs instead of the real user and group ID as required in a call to
 .Fn access .
 .It Dv AT_BENEATH
-Only operate on files and directories below the starting directory.
+Only operate on files and directories below the topping directory.
+See the description of the
+.Dv O_BENEATH
+flag in the
+.Xr open 2
+manual page.
 .El
 .Pp
 Even if a process's real or effective user has appropriate privileges
@@ -198,14 +203,23 @@ is neither
 .Dv AT_FDCWD
 nor a file descriptor associated with a directory.
 .It Bq Er ENOTCAPABLE
+.Fa path
+is an absolute path,
+or contained a ".." component leading to a
+directory outside of the directory hierarchy specified by
+.Fa fd ,
+and the process is in capability mode.
+.It Bq Er ENOTCAPABLE
 The
 .Dv AT_BENEATH
-flag was specified but
+flag was provided to
+.Fn faccessat ,
+and the absolute
 .Fa path
-is not strictly relative to the starting directory.
-For example,
+does not have its tail fully contained under the topping directory,
+or the relative
 .Fa path
-is absolute or includes a ".." component that escapes the starting directory.
+escapes it.
 .El
 .Sh SEE ALSO
 .Xr chmod 2 ,
diff --git a/lib/libc/sys/chflags.2 b/lib/libc/sys/chflags.2
index c9caea862009c..7db10569ea31c 100644
--- a/lib/libc/sys/chflags.2
+++ b/lib/libc/sys/chflags.2
@@ -28,7 +28,7 @@
 .\"	@(#)chflags.2	8.3 (Berkeley) 5/2/95
 .\" $FreeBSD$
 .\"
-.Dd October 20, 2018
+.Dd November 11, 2018
 .Dt CHFLAGS 2
 .Os
 .Sh NAME
@@ -96,7 +96,12 @@ If
 names a symbolic link, then the flags of the symbolic link are changed.
 .It Dv AT_BENEATH
 Only allow to change flags for a file which is beneath of
-the starting directory.
+the topping directory.
+See the description of the
+.Dv O_BENEATH
+flag in the
+.Xr open 2
+manual page.
 .El
 .Pp
 If
@@ -306,14 +311,23 @@ The underlying file system does not support file flags, or
 does not support all of the flags set in
 .Fa flags .
 .It Bq Er ENOTCAPABLE
+.Fa path
+is an absolute path,
+or contained a ".." component leading to a
+directory outside of the directory hierarchy specified by
+.Fa fd ,
+and the process is in capability mode.
+.It Bq Er ENOTCAPABLE
 The
 .Dv AT_BENEATH
-flag was specified but
+flag was provided to
+.Fn chflagsat ,
+and the absolute
 .Fa path
-is not strictly relative to the starting directory.
-For example,
+does not have its tail fully contained under the topping directory,
+or the relative
 .Fa path
-is absolute or includes a ".." component that escapes the starting directory.
+escapes it.
 .El
 .Sh SEE ALSO
 .Xr chflags 1 ,
diff --git a/lib/libc/sys/chmod.2 b/lib/libc/sys/chmod.2
index 65a7047293297..aef920ee6fefd 100644
--- a/lib/libc/sys/chmod.2
+++ b/lib/libc/sys/chmod.2
@@ -28,7 +28,7 @@
 .\"     @(#)chmod.2	8.1 (Berkeley) 6/4/93
 .\" $FreeBSD$
 .\"
-.Dd October 20, 2018
+.Dd November 11, 2018
 .Dt CHMOD 2
 .Os
 .Sh NAME
@@ -103,7 +103,12 @@ If
 names a symbolic link, then the mode of the symbolic link is changed.
 .It Dv AT_BENEATH
 Only allow to change permissions of a file which is beneath of
-the starting directory.
+the topping directory.
+See the description of the
+.Dv O_BENEATH
+flag in the
+.Xr open 2
+manual page.
 .El
 .Pp
 If
@@ -289,14 +294,23 @@ is neither
 .Dv AT_FDCWD
 nor a file descriptor associated with a directory.
 .It Bq Er ENOTCAPABLE
+.Fa path
+is an absolute path,
+or contained a ".." component leading to a
+directory outside of the directory hierarchy specified by
+.Fa fd ,
+and the process is in capability mode.
+.It Bq Er ENOTCAPABLE
 The
 .Dv AT_BENEATH
-flag was specified but
+flag was provided to
+.Fn fchmodat ,
+and the absolute
 .Fa path
-is not strictly relative to the starting directory.
-For example,
+does not have its tail fully contained under the topping directory,
+or the relative
 .Fa path
-is absolute or includes a ".." component that escapes the starting directory.
+escapes it.
 .El
 .Sh SEE ALSO
 .Xr chmod 1 ,
diff --git a/lib/libc/sys/chown.2 b/lib/libc/sys/chown.2
index 8ba2b9240b3d7..7eb8322c77d86 100644
--- a/lib/libc/sys/chown.2
+++ b/lib/libc/sys/chown.2
@@ -28,7 +28,7 @@
 .\"     @(#)chown.2	8.4 (Berkeley) 4/19/94
 .\" $FreeBSD$
 .\"
-.Dd Octover 20, 2018
+.Dd November 11, 2018
 .Dt CHOWN 2
 .Os
 .Sh NAME
@@ -120,7 +120,12 @@ If
 names a symbolic link, ownership of the symbolic link is changed.
 .It Dv AT_BENEATH
 Only allow to change ownership of a file which is beneath of
-the starting directory.
+the topping directory.
+See the description of the
+.Dv O_BENEATH
+flag in the
+.Xr open 2
+manual page.
 .El
 .Pp
 If
@@ -231,14 +236,23 @@ is neither
 .Dv AT_FDCWD
 nor a file descriptor associated with a directory.
 .It Bq Er ENOTCAPABLE
+.Fa path
+is an absolute path,
+or contained a ".." component leading to a
+directory outside of the directory hierarchy specified by
+.Fa fd ,
+and the process is in capability mode.
+.It Bq Er ENOTCAPABLE
 The
 .Dv AT_BENEATH
-flag was specified but
+flag was provided to
+.Fn fchownat ,
+and the absolute
 .Fa path
-is not strictly relative to the starting directory.
-For example,
+does not have its tail fully contained under the topping directory,
+or the relative
 .Fa path
-is absolute or includes a ".." component that escapes the starting directory.
+escapes it.
 .El
 .Sh SEE ALSO
 .Xr chgrp 1 ,
diff --git a/lib/libc/sys/link.2 b/lib/libc/sys/link.2
index 057f2aeccd522..3c6e32b3e9a5a 100644
--- a/lib/libc/sys/link.2
+++ b/lib/libc/sys/link.2
@@ -28,7 +28,7 @@
 .\"     @(#)link.2	8.3 (Berkeley) 1/12/94
 .\" $FreeBSD$
 .\"
-.Dd October 20, 2018
+.Dd November 11, 2018
 .Dt LINK 2
 .Os
 .Sh NAME
@@ -116,7 +116,12 @@ If
 names a symbolic link, a new link for the target of the symbolic link is
 created.
 .It Dv AT_BENEATH
-Only allow to link to a file which is beneath of the starting directory.
+Only allow to link to a file which is beneath of the topping directory.
+See the description of the
+.Dv O_BENEATH
+flag in the
+.Xr open 2
+manual page.
 .El
 .Pp
 If
@@ -260,16 +265,25 @@ respectively, is neither
 .Dv AT_FDCWD
 nor a file descriptor associated with a directory.
 .It Bq Er ENOTCAPABLE
-The
-.Dv AT_BENEATH
-flag was specified but
 .Fa name1
 is not strictly relative to the starting directory.
 For example,
 .Fa name1
-is absolute or includes a ".." component that escapes the starting directory.
+is absolute or includes a ".." component that escapes
+the directory hierarchy specified by
+.Fa fd ,
+and the process is in capability mode.
+.It Bq Er ENOTCAPABLE
+The
 .Dv AT_BENEATH
-flag was specified.
+flag was provided to
+.Fa linkat
+and the absolute path
+.Fa name1
+does not have its tail fully contained under the topping directory,
+or the relative path
+.Fa name1
+escapes it.
 .El
 .Sh SEE ALSO
 .Xr chflags 2 ,
diff --git a/lib/libc/sys/open.2 b/lib/libc/sys/open.2
index d98d5b62a227e..012e0afd23d89 100644
--- a/lib/libc/sys/open.2
+++ b/lib/libc/sys/open.2
@@ -28,7 +28,7 @@
 .\"     @(#)open.2	8.2 (Berkeley) 11/16/93
 .\" $FreeBSD$
 .\"
-.Dd October 20, 2018
+.Dd November 11, 2018
 .Dt OPEN 2
 .Os
 .Sh NAME
@@ -75,8 +75,14 @@ function is equivalent to the
 .Fn open
 function except in the case where the
 .Fa path
-specifies a relative path.
-In this case the file to be opened is determined relative to the directory
+specifies a relative path, or the
+.Dv O_BENEATH
+flag is provided.
+For
+.Fn openat
+and relative
+.Fa path ,
+the file to be opened is determined relative to the directory
 associated with the file descriptor
 .Fa fd
 instead of the current working directory.
@@ -95,6 +101,26 @@ parameter, the current working directory is used
 and the behavior is identical to a call to
 .Fn open .
 .Pp
+When
+.Fn openat
+is called with an absolute
+.Fa path
+without the
+.Dv O_BENEATH
+flag, it ignores the
+.Fa fd
+argument.
+When
+.Dv O_BENEATH
+is specified with an absolute
+.Fa path ,
+a directory passed by the
+.Fa fd
+argument is used as the topping point for the resolution.
+See the definition of the
+.Dv O_BENEATH
+flag below.
+.Pp
 In
 .Xr capsicum 4
 capability mode,
@@ -109,14 +135,28 @@ must be strictly relative to a file descriptor
 as defined in
 .Pa sys/kern/vfs_lookup.c .
 .Fa path
-must not be an absolute path and must not contain ".." components.
+must not be an absolute path and must not contain ".." components
+which cause the path resolution to escape the directory hierarchy
+starting at
+.Fa fd .
 Additionally, no symbolic link in
 .Fa path
-may contain ".." components either.
+may target absolute path or contain escaping ".." components.
 .Fa fd
 must not be
 .Dv AT_FDCWD .
 .Pp
+If the
+.Dv vfs.lookup_cap_dotdot
+.Xr sysctl 3
+MIB is set to zero, ".." components in the paths,
+used in capability mode, or with the
+.Dv O_BENEATH
+flag, are completely disabled.
+If the
+.Dv vfs.lookup_cap_dotdot_nonlocal
+MIB is set to zero, ".." is not allowed if found on non-local filesystem.
+.Pp
 The flags specified are formed by
 .Em or Ns 'ing
 the following values
@@ -142,7 +182,7 @@ O_TTY_INIT	ignored
 O_DIRECTORY	error if file is not a directory
 O_CLOEXEC	set FD_CLOEXEC upon open
 O_VERIFY	verify the contents of the file
-O_BENEATH	require path to be strictly relative to starting directory
+O_BENEATH	require path to be strictly relative to topping directory
 .Ed
 .Pp
 Opening a file with
@@ -273,19 +313,21 @@ been verified before operating on them.
 .Dv O_BENEATH
 returns
 .Er ENOTCAPABLE
-if the specified path, after resolving all symlinks and ".." references
-in it, does not reside in the directory hierarchy of children beneath
-the starting directory, or is an absolute path.
-Starting directory is the process current directory if relative
+if the specified relative path, after resolving all symlinks and ".."
+references, does not reside in the directory hierarchy of
+children beneath the topping directory.
+Topping directory is the process current directory if relative
 .Fa path
 is used for
 .Fn open ,
 and the directory referenced by the
 .Fa fd
-argument when specifying relative
-.Fa path
-for
+argument when using
 .Fn openat .
+If the specified path is absolute,
+.Dv O_BENEATH
+allows arbitrary prefix that ends up at the topping directory,
+after which all further resolved components must be under it.
 .Pp
 If successful,
 .Fn open
@@ -509,9 +551,16 @@ is an absolute path,
 or contained a ".." component leading to a
 directory outside of the directory hierarchy specified by
 .Fa fd ,
-and the process is in capability mode or the
+and the process is in capability mode.
+.It Bq Er ENOTCAPABLE
+The
 .Dv O_BENEATH
-flag was provided.
+flag was provided, and the absolute
+.Fa path
+does not have its tail fully contained under the topping directory,
+or the relative
+.Fa path
+escapes it.
 .El
 .Sh SEE ALSO
 .Xr chmod 2 ,
diff --git a/lib/libc/sys/stat.2 b/lib/libc/sys/stat.2
index 37b04aedcd801..f72dc0d0a117a 100644
--- a/lib/libc/sys/stat.2
+++ b/lib/libc/sys/stat.2
@@ -28,7 +28,7 @@
 .\"     @(#)stat.2	8.4 (Berkeley) 5/1/95
 .\" $FreeBSD$
 .\"
-.Dd October 20, 2018
+.Dd November 11, 2018
 .Dt STAT 2
 .Os
 .Sh NAME
@@ -84,11 +84,24 @@ and
 .Fn lstat
 except when the
 .Fa path
-specifies a relative path.
-In this case the status is retrieved from a file relative to
+specifies a relative path, or the
+.Dv AT_BENEATH
+flag is provided.
+For
+.Fn fstatat
+and relative
+.Fa path ,
+the status is retrieved from a file relative to
 the directory associated with the file descriptor
 .Fa fd
 instead of the current working directory.
+For
+.Dv AT_BENEATH
+and absolute
+.Fa path ,
+the status is retrieved from a file specified by the
+.Fa path ,
+but additional permission checks are performed, see below.
 .Pp
 The values for the
 .Fa flag
@@ -101,7 +114,7 @@ If
 .Fa path
 names a symbolic link, the status of the symbolic link is returned.
 .It Dv AT_BENEATH
-Only stat files and directories below the starting directory.
+Only stat files and directories below the topping directory.
 See the description of the
 .Dv O_BENEATH
 flag in the
@@ -125,6 +138,23 @@ respectively, depending on whether or not the
 bit is set in
 .Fa flag .
 .Pp
+When
+.Fn fstatat
+is called with an absolute
+.Fa path
+without the
+.Dv AT_BENEATH
+flag, it ignores the
+.Fa fd
+argument.
+When
+.Dv AT_BENEATH
+is specified with an absolute
+.Fa path ,
+a directory passed by the
+.Fa fd
+argument is used as the topping point for the resolution.
+.Pp
 The
 .Fa sb
 argument is a pointer to a
@@ -405,14 +435,23 @@ is neither
 .Dv AT_FDCWD
 nor a file descriptor associated with a directory.
 .It Bq Er ENOTCAPABLE
+.Fa path
+is an absolute path,
+or contained a ".." component leading to a
+directory outside of the directory hierarchy specified by
+.Fa fd ,
+and the process is in capability mode.
+.It Bq Er ENOTCAPABLE
 The
 .Dv AT_BENEATH
-flag was specified but
+flag was provided to
+.Fn fstatat ,
+and the absolute
 .Fa path
-is not strictly relative to the starting directory.
-For example,
+does not have its tail fully contained under the topping directory,
+or the relative
 .Fa path
-is absolute or includes a ".." component that escapes the starting directory.
+escapes it.
 .El
 .Sh SEE ALSO
 .Xr access 2 ,
diff --git a/lib/libc/sys/unlink.2 b/lib/libc/sys/unlink.2
index 2e0ed54b0a297..c6c6a150c1a20 100644
--- a/lib/libc/sys/unlink.2
+++ b/lib/libc/sys/unlink.2
@@ -28,7 +28,7 @@
 .\"     @(#)unlink.2	8.1 (Berkeley) 6/4/93
 .\" $FreeBSD$
 .\"
-.Dd October 20, 2018
+.Dd November 11, 2018
 .Dt UNLINK 2
 .Os
 .Sh NAME
@@ -90,8 +90,13 @@ and
 .Fa path
 as a directory, not a normal file.
 .It Dv AT_BENEATH
-Only unlink files and directories which are beneath of the starting
+Only unlink files and directories which are beneath of the topping
 directory.
+See the description of the
+.Dv O_BENEATH
+flag in the
+.Xr open 2
+manual page.
 .El
 .Pp
 If
@@ -204,14 +209,23 @@ is neither
 .Dv AT_FDCWD
 nor a file descriptor associated with a directory.
 .It Bq Er ENOTCAPABLE
+.Fa path
+is an absolute path,
+or contained a ".." component leading to a
+directory outside of the directory hierarchy specified by
+.Fa fd ,
+and the process is in capability mode.
+.It Bq Er ENOTCAPABLE
 The
 .Dv AT_BENEATH
-flag was specified but
+flag was provided to
+.Fn unlinkat ,
+and the absolute
 .Fa path
-is not strictly relative to the starting directory.
-For example,
+does not have its tail fully contained under the topping directory,
+or the relative
 .Fa path
-is absolute or includes a ".." component that escapes the starting directory.
+escapes it.
 .El
 .Sh SEE ALSO
 .Xr chflags 2 ,
diff --git a/lib/libc/sys/utimensat.2 b/lib/libc/sys/utimensat.2
index 7fcb3c6696974..cf7ba290a813c 100644
--- a/lib/libc/sys/utimensat.2
+++ b/lib/libc/sys/utimensat.2
@@ -31,7 +31,7 @@
 .\"     @(#)utimes.2	8.1 (Berkeley) 6/4/93
 .\" $FreeBSD$
 .\"
-.Dd October 20, 2018
+.Dd November 11, 2018
 .Dt UTIMENSAT 2
 .Os
 .Sh NAME
@@ -148,7 +148,12 @@ By default,
 changes the times of the file referenced by the symbolic link.
 .It Dv AT_BENEATH
 Only allow to change the times of a file which is beneath of
-the starting directory.
+the topping directory.
+See the description of the
+.Dv O_BENEATH
+flag in the
+.Xr open 2
+manual page.
 .El
 .Sh RETURN VALUES
 .Rv -std
@@ -271,14 +276,23 @@ is neither
 .Dv AT_FDCWD
 nor a file descriptor associated with a directory.
 .It Bq Er ENOTCAPABLE
+.Fa path
+is an absolute path,
+or contained a ".." component leading to a
+directory outside of the directory hierarchy specified by
+.Fa fd ,
+and the process is in capability mode.
+.It Bq Er ENOTCAPABLE
 The
 .Dv AT_BENEATH
-flag was specified but
+flag was provided to
+.Fn utimensat ,
+and the absolute
 .Fa path
-is not strictly relative to the starting directory.
-For example,
+does not have its tail fully contained under the topping directory,
+or the relative
 .Fa path
-is absolute or includes a ".." component that escapes the starting directory.
+escapes it.
 .El
 .Sh SEE ALSO
 .Xr chflags 2 ,