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

11 files changed, 221 insertions, 221 deletions

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