mdoc: move CAVEATS, BUGS and SECURITY CONSIDERATIONS sections to the

bottom of the manpages and order them consistently.

GNU groff doesn't care about the ordering, and doesn't even mention
CAVEATS and SECURITY CONSIDERATIONS as common sections and where to put
them.

Found by:	mdocml lint run
Reviewed by:	ru

15 files changed, 262 insertions, 262 deletions

diff --git a/lib/libarchive/cpio.5 b/lib/libarchive/cpio.5
index 02077d6..5bc60fe 100644
--- a/lib/libarchive/cpio.5
+++ b/lib/libarchive/cpio.5
@@ -268,31 +268,6 @@ data, including ACLs and extended attributes, as special
 entries in cpio archives.
 .Pp
 XXX Others? XXX
-.Sh BUGS
-The
-.Dq CRC
-format is mis-named, as it uses a simple checksum and
-not a cyclic redundancy check.
-.Pp
-The old binary format is limited to 16 bits for user id,
-group id, device, and inode numbers.
-It is limited to 4 gigabyte file sizes.
-.Pp
-The old ASCII format is limited to 18 bits for
-the user id, group id, device, and inode numbers.
-It is limited to 8 gigabyte file sizes.
-.Pp
-The new ASCII format is limited to 4 gigabyte file sizes.
-.Pp
-None of the cpio formats store user or group names,
-which are essential when moving files between systems with
-dissimilar user or group numbering.
-.Pp
-Especially when writing older cpio variants, it may be necessary
-to map actual device/inode values to synthesized values that
-fit the available fields.
-With very large filesystems, this may be necessary even for
-the newer formats.
 .Sh SEE ALSO
 .Xr cpio 1 ,
 .Xr tar 5
@@ -323,3 +298,28 @@ license.
 The character format was adopted as part of
 .St -p1003.1-88 .
 XXX when did "newc" appear?  Who invented it?  When did HP come out with their variant?  When did Sun introduce ACLs and extended attributes? XXX
+.Sh BUGS
+The
+.Dq CRC
+format is mis-named, as it uses a simple checksum and
+not a cyclic redundancy check.
+.Pp
+The old binary format is limited to 16 bits for user id,
+group id, device, and inode numbers.
+It is limited to 4 gigabyte file sizes.
+.Pp
+The old ASCII format is limited to 18 bits for
+the user id, group id, device, and inode numbers.
+It is limited to 8 gigabyte file sizes.
+.Pp
+The new ASCII format is limited to 4 gigabyte file sizes.
+.Pp
+None of the cpio formats store user or group names,
+which are essential when moving files between systems with
+dissimilar user or group numbering.
+.Pp
+Especially when writing older cpio variants, it may be necessary
+to map actual device/inode values to synthesized values that
+fit the available fields.
+With very large filesystems, this may be necessary even for
+the newer formats.
diff --git a/lib/libc/gen/fmtcheck.3 b/lib/libc/gen/fmtcheck.3
index 2fa587b..0bd4299 100644
--- a/lib/libc/gen/fmtcheck.3
+++ b/lib/libc/gen/fmtcheck.3
@@ -87,6 +87,12 @@ will return
 .Fa fmt_suspect .
 Otherwise, it will return
 .Fa fmt_default .
+.Sh SEE ALSO
+.Xr printf 3
+.Sh BUGS
+The
+.Fn fmtcheck
+function does not recognize positional parameters.
 .Sh SECURITY CONSIDERATIONS
 Note that the formats may be quite different as long as they accept the
 same arguments.
@@ -100,9 +106,3 @@ is not equivalent to
 .Qq Li %lx
 because
 the first requires an integer and the second requires a long.
-.Sh SEE ALSO
-.Xr printf 3
-.Sh BUGS
-The
-.Fn fmtcheck
-function does not recognize positional parameters.
diff --git a/lib/libc/stdio/fgets.3 b/lib/libc/stdio/fgets.3
index aa8e2ac..fba7353 100644
--- a/lib/libc/stdio/fgets.3
+++ b/lib/libc/stdio/fgets.3
@@ -128,6 +128,19 @@ may also fail and set
 .Va errno
 for any of the errors specified for the routine
 .Xr getchar 3 .
+.Sh SEE ALSO
+.Xr feof 3 ,
+.Xr ferror 3 ,
+.Xr fgetln 3 ,
+.Xr fgetws 3 ,
+.Xr getline 3
+.Sh STANDARDS
+The functions
+.Fn fgets
+and
+.Fn gets
+conform to
+.St -isoC-99 .
 .Sh SECURITY CONSIDERATIONS
 The
 .Fn gets
@@ -143,16 +156,3 @@ It is strongly suggested that the
 function be used in all cases.
 (See
 the FSA.)
-.Sh SEE ALSO
-.Xr feof 3 ,
-.Xr ferror 3 ,
-.Xr fgetln 3 ,
-.Xr fgetws 3 ,
-.Xr getline 3
-.Sh STANDARDS
-The functions
-.Fn fgets
-and
-.Fn gets
-conform to
-.St -isoC-99 .
diff --git a/lib/libc/stdio/printf.3 b/lib/libc/stdio/printf.3
index 2c031f7..90a8ed8 100644
--- a/lib/libc/stdio/printf.3
+++ b/lib/libc/stdio/printf.3
@@ -709,77 +709,6 @@ char *newfmt(const char *fmt, ...)
 	return (p);
 }
 .Ed
-.Sh SECURITY CONSIDERATIONS
-The
-.Fn sprintf
-and
-.Fn vsprintf
-functions are easily misused in a manner which enables malicious users
-to arbitrarily change a running program's functionality through
-a buffer overflow attack.
-Because
-.Fn sprintf
-and
-.Fn vsprintf
-assume an infinitely long string,
-callers must be careful not to overflow the actual space;
-this is often hard to assure.
-For safety, programmers should use the
-.Fn snprintf
-interface instead.
-For example:
-.Bd -literal
-void
-foo(const char *arbitrary_string, const char *and_another)
-{
-	char onstack[8];
-
-#ifdef BAD
-	/*
-	 * This first sprintf is bad behavior.  Do not use sprintf!
-	 */
-	sprintf(onstack, "%s, %s", arbitrary_string, and_another);
-#else
-	/*
-	 * The following two lines demonstrate better use of
-	 * snprintf().
-	 */
-	snprintf(onstack, sizeof(onstack), "%s, %s", arbitrary_string,
-	    and_another);
-#endif
-}
-.Ed
-.Pp
-The
-.Fn printf
-and
-.Fn sprintf
-family of functions are also easily misused in a manner
-allowing malicious users to arbitrarily change a running program's
-functionality by either causing the program
-to print potentially sensitive data
-.Dq "left on the stack" ,
-or causing it to generate a memory fault or bus error
-by dereferencing an invalid pointer.
-.Pp
-.Cm %n
-can be used to write arbitrary data to potentially carefully-selected
-addresses.
-Programmers are therefore strongly advised to never pass untrusted strings
-as the
-.Fa format
-argument, as an attacker can put format specifiers in the string
-to mangle your stack,
-leading to a possible security hole.
-This holds true even if the string was built using a function like
-.Fn snprintf ,
-as the resulting string may still contain user-supplied conversion specifiers
-for later interpolation by
-.Fn printf .
-.Pp
-Always use the proper secure idiom:
-.Pp
-.Dl "snprintf(buffer, sizeof(buffer), \*q%s\*q, string);"
 .Sh COMPATIBILITY
 Many application writers used the name
 .Va dprintf
@@ -906,3 +835,74 @@ The
 family of functions do not correctly handle multibyte characters in the
 .Fa format
 argument.
+.Sh SECURITY CONSIDERATIONS
+The
+.Fn sprintf
+and
+.Fn vsprintf
+functions are easily misused in a manner which enables malicious users
+to arbitrarily change a running program's functionality through
+a buffer overflow attack.
+Because
+.Fn sprintf
+and
+.Fn vsprintf
+assume an infinitely long string,
+callers must be careful not to overflow the actual space;
+this is often hard to assure.
+For safety, programmers should use the
+.Fn snprintf
+interface instead.
+For example:
+.Bd -literal
+void
+foo(const char *arbitrary_string, const char *and_another)
+{
+	char onstack[8];
+
+#ifdef BAD
+	/*
+	 * This first sprintf is bad behavior.  Do not use sprintf!
+	 */
+	sprintf(onstack, "%s, %s", arbitrary_string, and_another);
+#else
+	/*
+	 * The following two lines demonstrate better use of
+	 * snprintf().
+	 */
+	snprintf(onstack, sizeof(onstack), "%s, %s", arbitrary_string,
+	    and_another);
+#endif
+}
+.Ed
+.Pp
+The
+.Fn printf
+and
+.Fn sprintf
+family of functions are also easily misused in a manner
+allowing malicious users to arbitrarily change a running program's
+functionality by either causing the program
+to print potentially sensitive data
+.Dq "left on the stack" ,
+or causing it to generate a memory fault or bus error
+by dereferencing an invalid pointer.
+.Pp
+.Cm %n
+can be used to write arbitrary data to potentially carefully-selected
+addresses.
+Programmers are therefore strongly advised to never pass untrusted strings
+as the
+.Fa format
+argument, as an attacker can put format specifiers in the string
+to mangle your stack,
+leading to a possible security hole.
+This holds true even if the string was built using a function like
+.Fn snprintf ,
+as the resulting string may still contain user-supplied conversion specifiers
+for later interpolation by
+.Fn printf .
+.Pp
+Always use the proper secure idiom:
+.Pp
+.Dl "snprintf(buffer, sizeof(buffer), \*q%s\*q, string);"
diff --git a/lib/libc/stdio/tmpnam.3 b/lib/libc/stdio/tmpnam.3
index 66652b7..937068f 100644
--- a/lib/libc/stdio/tmpnam.3
+++ b/lib/libc/stdio/tmpnam.3
@@ -217,6 +217,17 @@ for any of the errors specified for the library functions
 .Xr malloc 3
 or
 .Xr mktemp 3 .
+.Sh SEE ALSO
+.Xr mkstemp 3 ,
+.Xr mktemp 3
+.Sh STANDARDS
+The
+.Fn tmpfile
+and
+.Fn tmpnam
+functions
+conform to
+.St -isoC .
 .Sh SECURITY CONSIDERATIONS
 The
 .Fn tmpnam
@@ -235,14 +246,3 @@ It is strongly suggested that
 be used in place of these functions.
 (See
 the FSA.)
-.Sh SEE ALSO
-.Xr mkstemp 3 ,
-.Xr mktemp 3
-.Sh STANDARDS
-The
-.Fn tmpfile
-and
-.Fn tmpnam
-functions
-conform to
-.St -isoC .
diff --git a/lib/libc/stdio/wprintf.3 b/lib/libc/stdio/wprintf.3
index 3e91846..fecb586 100644
--- a/lib/libc/stdio/wprintf.3
+++ b/lib/libc/stdio/wprintf.3
@@ -588,9 +588,6 @@ In no case does a non-existent or small field width cause truncation of
 a numeric field; if the result of a conversion is wider than the field
 width, the
 field is expanded to contain the conversion result.
-.Sh SECURITY CONSIDERATIONS
-Refer to
-.Xr printf 3 .
 .Sh SEE ALSO
 .Xr btowc 3 ,
 .Xr fputws 3 ,
@@ -616,3 +613,6 @@ and
 functions
 conform to
 .St -isoC-99 .
+.Sh SECURITY CONSIDERATIONS
+Refer to
+.Xr printf 3 .
diff --git a/lib/libc/stdlib/realpath.3 b/lib/libc/stdlib/realpath.3
index 166bb12..57ad4ba 100644
--- a/lib/libc/stdlib/realpath.3
+++ b/lib/libc/stdlib/realpath.3
@@ -109,6 +109,18 @@ for any of the errors specified for the library functions
 .Xr readlink 2
 and
 .Xr getcwd 3 .
+.Sh SEE ALSO
+.Xr getcwd 3
+.Sh STANDARDS
+The
+.Fn realpath
+function conforms to
+.St -p1003.1-2001 .
+.Sh HISTORY
+The
+.Fn realpath
+function first appeared in
+.Bx 4.4 .
 .Sh CAVEATS
 This implementation of
 .Fn realpath
@@ -121,15 +133,3 @@ under certain circumstances, return a relative
 .Fa resolved_path
 when given a relative
 .Fa pathname .
-.Sh "SEE ALSO"
-.Xr getcwd 3
-.Sh STANDARDS
-The
-.Fn realpath
-function conforms to
-.St -p1003.1-2001 .
-.Sh HISTORY
-The
-.Fn realpath
-function first appeared in
-.Bx 4.4 .
diff --git a/lib/libc/string/strcat.3 b/lib/libc/string/strcat.3
index 4c9fec9..dfa55a4 100644
--- a/lib/libc/string/strcat.3
+++ b/lib/libc/string/strcat.3
@@ -80,6 +80,23 @@ and
 functions
 return the pointer
 .Fa s .
+.Sh SEE ALSO
+.Xr bcopy 3 ,
+.Xr memccpy 3 ,
+.Xr memcpy 3 ,
+.Xr memmove 3 ,
+.Xr strcpy 3 ,
+.Xr strlcat 3 ,
+.Xr strlcpy 3 ,
+.Xr wcscat 3
+.Sh STANDARDS
+The
+.Fn strcat
+and
+.Fn strncat
+functions
+conform to
+.St -isoC .
 .Sh SECURITY CONSIDERATIONS
 The
 .Fn strcat
@@ -138,20 +155,3 @@ foo(const char *arbitrary_string)
 #endif
 }
 .Ed
-.Sh SEE ALSO
-.Xr bcopy 3 ,
-.Xr memccpy 3 ,
-.Xr memcpy 3 ,
-.Xr memmove 3 ,
-.Xr strcpy 3 ,
-.Xr strlcat 3 ,
-.Xr strlcpy 3 ,
-.Xr wcscat 3
-.Sh STANDARDS
-The
-.Fn strcat
-and
-.Fn strncat
-functions
-conform to
-.St -isoC .
diff --git a/lib/libc/string/strcpy.3 b/lib/libc/string/strcpy.3
index 157abcc..395e2f9 100644
--- a/lib/libc/string/strcpy.3
+++ b/lib/libc/string/strcpy.3
@@ -174,16 +174,6 @@ Note that because
 .Xr strlcpy 3
 is not defined in any standards, it should
 only be used when portability is not a concern.
-.Sh SECURITY CONSIDERATIONS
-The
-.Fn strcpy
-function is easily misused in a manner which enables malicious users
-to arbitrarily change a running program's functionality through a
-buffer overflow attack.
-(See
-the FSA
-and
-.Sx EXAMPLES . )
 .Sh SEE ALSO
 .Xr bcopy 3 ,
 .Xr memccpy 3 ,
@@ -214,3 +204,13 @@ and
 .Fn stpncpy
 was added in
 .Fx 8.0 .
+.Sh SECURITY CONSIDERATIONS
+The
+.Fn strcpy
+function is easily misused in a manner which enables malicious users
+to arbitrarily change a running program's functionality through a
+buffer overflow attack.
+(See
+the FSA
+and
+.Sx EXAMPLES . )
diff --git a/lib/libc/sys/access.2 b/lib/libc/sys/access.2
index 0cd3c6f..65b8fb6 100644
--- a/lib/libc/sys/access.2
+++ b/lib/libc/sys/access.2
@@ -188,6 +188,27 @@ is neither
 .Dv AT_FDCWD
 nor a file descriptor associated with a directory.
 .El
+.Sh SEE ALSO
+.Xr chmod 2 ,
+.Xr intro 2 ,
+.Xr stat 2
+.Sh STANDARDS
+The
+.Fn access
+system call is expected to conform to
+.St -p1003.1-90 .
+The
+.Fn faccessat
+system call follows The Open Group Extended API Set 2 specification.
+.Sh HISTORY
+The
+.Fn access
+function appeared in
+.At v7 .
+The
+.Fn faccessat
+system call appeared in
+.Fx 8.0 .
 .Sh SECURITY CONSIDERATIONS
 The
 .Fn access
@@ -212,24 +233,3 @@ of the st_mode bits that the application might not understand --
 e.g. in the case of AFS).
 It also allows a cheaper file existence test than
 .Xr stat 2 .
-.Sh SEE ALSO
-.Xr chmod 2 ,
-.Xr intro 2 ,
-.Xr stat 2
-.Sh STANDARDS
-The
-.Fn access
-system call is expected to conform to
-.St -p1003.1-90 .
-The
-.Fn faccessat
-system call follows The Open Group Extended API Set 2 specification.
-.Sh HISTORY
-The
-.Fn access
-function appeared in
-.At v7 .
-The
-.Fn faccessat
-system call appeared in
-.Fx 8.0 .
diff --git a/lib/libc/sys/execve.2 b/lib/libc/sys/execve.2
index acc6471..0559a1a 100644
--- a/lib/libc/sys/execve.2
+++ b/lib/libc/sys/execve.2
@@ -313,30 +313,6 @@ The
 .Fa fd
 argument is not a valid file descriptor open for executing.
 .El
-.Sh CAVEATS
-If a program is
-.Em setuid
-to a non-super-user, but is executed when
-the real
-.Em uid
-is ``root'', then the program has some of the powers
-of a super-user as well.
-.Pp
-When executing an interpreted program through
-.Fn fexecve ,
-kernel supplies
-.Pa /dev/fd/n
-as a second argument to the interpreter,
-where
-.Ar n
-is the file descriptor passed in the
-.Fa fd
-argument to
-.Fn fexecve .
-For this construction to work correctly, the
-.Xr fdescfs 5
-filesystem shall be mounted on
-.Pa /dev/fd .
 .Sh SEE ALSO
 .Xr ktrace 1 ,
 .Xr _exit 2 ,
@@ -373,3 +349,27 @@ The
 .Fn fexecve
 system call appeared in
 .Fx 8.0 .
+.Sh CAVEATS
+If a program is
+.Em setuid
+to a non-super-user, but is executed when
+the real
+.Em uid
+is ``root'', then the program has some of the powers
+of a super-user as well.
+.Pp
+When executing an interpreted program through
+.Fn fexecve ,
+kernel supplies
+.Pa /dev/fd/n
+as a second argument to the interpreter,
+where
+.Ar n
+is the file descriptor passed in the
+.Fa fd
+argument to
+.Fn fexecve .
+For this construction to work correctly, the
+.Xr fdescfs 5
+filesystem shall be mounted on
+.Pa /dev/fd .
diff --git a/lib/libc/sys/setuid.2 b/lib/libc/sys/setuid.2
index 78e4ab8..4bb4a68 100644
--- a/lib/libc/sys/setuid.2
+++ b/lib/libc/sys/setuid.2
@@ -124,39 +124,6 @@ The system calls will fail if:
 The user is not the super user and the ID
 specified is not the real, effective ID, or saved ID.
 .El
-.Sh SECURITY CONSIDERATIONS
-Read and write permissions to files are determined upon a call to
-.Xr open 2 .
-Once a file descriptor is open, dropping privilege does not affect
-the process's read/write permissions, even if the user ID specified
-has no read or write permissions to the file.
-These files normally remain open in any new process executed,
-resulting in a user being able to read or modify
-potentially sensitive data.
-.Pp
-To prevent these files from remaining open after an
-.Xr exec 3
-call, be sure to set the close-on-exec flag is set:
-.Bd -literal
-void
-pseudocode(void)
-{
-	int fd;
-	/* ... */
-
-	fd = open("/path/to/sensitive/data", O_RDWR);
-	if (fd == -1)
-		err(1, "open");
-
-	/*
-	 * Set close-on-exec flag; see fcntl(2) for more information.
-	 */
-	if (fcntl(fd, F_SETFD, FD_CLOEXEC) == -1)
-		err(1, "fcntl(F_SETFD)");
-	/* ... */
-	execve(path, argv, environ);
-}
-.Ed
 .Sh SEE ALSO
 .Xr getgid 2 ,
 .Xr getuid 2 ,
@@ -191,3 +158,36 @@ and
 .Fn setgid
 functions appeared in
 .At v7 .
+.Sh SECURITY CONSIDERATIONS
+Read and write permissions to files are determined upon a call to
+.Xr open 2 .
+Once a file descriptor is open, dropping privilege does not affect
+the process's read/write permissions, even if the user ID specified
+has no read or write permissions to the file.
+These files normally remain open in any new process executed,
+resulting in a user being able to read or modify
+potentially sensitive data.
+.Pp
+To prevent these files from remaining open after an
+.Xr exec 3
+call, be sure to set the close-on-exec flag is set:
+.Bd -literal
+void
+pseudocode(void)
+{
+	int fd;
+	/* ... */
+
+	fd = open("/path/to/sensitive/data", O_RDWR);
+	if (fd == -1)
+		err(1, "open");
+
+	/*
+	 * Set close-on-exec flag; see fcntl(2) for more information.
+	 */
+	if (fcntl(fd, F_SETFD, FD_CLOEXEC) == -1)
+		err(1, "fcntl(F_SETFD)");
+	/* ... */
+	execve(path, argv, environ);
+}
+.Ed
diff --git a/lib/libpmc/pmc.mips.3 b/lib/libpmc/pmc.mips.3
index f9ec1d0..3fe6825 100644
--- a/lib/libpmc/pmc.mips.3
+++ b/lib/libpmc/pmc.mips.3
@@ -392,8 +392,6 @@ and the underlying hardware events used.
 .Xr pmc_cpuinfo 3 ,
 .Xr pmclog 3 ,
 .Xr hwpmc 4
-.Sh CAVEATS
-The MIPS code does not yet support sampling.
 .Sh HISTORY
 The
 .Nm pmc
@@ -408,3 +406,5 @@ library was written by
 MIPS support was added by
 .An "George Neville-Neil"
 .Aq gnn@FreeBSD.org .
+.Sh CAVEATS
+The MIPS code does not yet support sampling.
diff --git a/lib/libpmc/pmc.xscale.3 b/lib/libpmc/pmc.xscale.3
index 3cb64c3..955a84b 100644
--- a/lib/libpmc/pmc.xscale.3
+++ b/lib/libpmc/pmc.xscale.3
@@ -135,8 +135,6 @@ and the underlying hardware events used.
 .Xr pmc_cpuinfo 3 ,
 .Xr pmclog 3 ,
 .Xr hwpmc 4
-.Sh CAVEATS
-The Intel XScale code does not yet support sampling.
 .Sh HISTORY
 The
 .Nm pmc
@@ -154,3 +152,5 @@ library was written by
 Intel XScale support was added by
 .An "Rui Paulo"
 .Aq rpaulo@FreeBSD.org .
+.Sh CAVEATS
+The Intel XScale code does not yet support sampling.
diff --git a/lib/msun/man/fenv.3 b/lib/msun/man/fenv.3
index 728874e..aaea5f5 100644
--- a/lib/msun/man/fenv.3
+++ b/lib/msun/man/fenv.3
@@ -196,18 +196,6 @@ environment.
 The macro
 .Dv FE_DFL_ENV
 expands to a pointer to the default environment.
-.Sh CAVEATS
-The FENV_ACCESS pragma can be enabled with
-.Dl "#pragma STDC FENV_ACCESS ON"
-and disabled with the
-.Dl "#pragma STDC FENV_ACCESS OFF"
-directive.
-This lexically-scoped annotation tells the compiler that the program
-may access the floating-point environment, so optimizations that would
-violate strict IEEE-754 semantics are disabled.
-If execution reaches a block of code for which
-.Dv FENV_ACCESS
-is off, the floating-point environment will become undefined.
 .Sh EXAMPLES
 The following routine computes the square root function.
 It explicitly raises an invalid exception on appropriate inputs using
@@ -274,6 +262,18 @@ It supersedes the non-standard routines defined in
 .In ieeefp.h
 and documented in
 .Xr fpgetround 3 .
+.Sh CAVEATS
+The FENV_ACCESS pragma can be enabled with
+.Dl "#pragma STDC FENV_ACCESS ON"
+and disabled with the
+.Dl "#pragma STDC FENV_ACCESS OFF"
+directive.
+This lexically-scoped annotation tells the compiler that the program
+may access the floating-point environment, so optimizations that would
+violate strict IEEE-754 semantics are disabled.
+If execution reaches a block of code for which
+.Dv FENV_ACCESS
+is off, the floating-point environment will become undefined.
 .Sh BUGS
 The
 .Dv FENV_ACCESS