realpath: Improve manual page

* Try to make the RETURN VALUES section flow better.

* Add basename(3), dirname(3), free(3) to the SEE ALSO section.

* Drop the CAVEATS section, which was obsolete the moment realpath(3)
  was added to the Single Unix Specification in 1994.

MFC after:      1 week
Sponsored by:   Klara, Inc.
Reviewed by:	kevans
Differential Revision:	https://reviews.freebsd.org/D55928

1 files changed, 12 insertions, 24 deletions

diff --git a/lib/libc/stdlib/realpath.3 b/lib/libc/stdlib/realpath.3
index 76f40249963b..a17ddee0b2f1 100644
--- a/lib/libc/stdlib/realpath.3
+++ b/lib/libc/stdlib/realpath.3
@@ -28,7 +28,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd October 10, 2025
+.Dd March 18, 2026
 .Dt REALPATH 3
 .Os
 .Sh NAME
@@ -75,27 +75,24 @@ must exist when
 is called, and all but the last component must name either directories or
 symlinks pointing to the directories.
 .Sh "RETURN VALUES"
-The
+On success, the
 .Fn realpath
 function returns
 .Fa resolved_path
-on success.
-If the function was supplied
-.Dv NULL
-as
-.Fa resolved_path ,
-and operation did not cause errors, the returned value is
-a null-terminated string in a buffer allocated by a call to
-.Fn malloc 3 .
+if it was not
+.Dv NULL ,
+or a pointer to a null-terminated string which must be freed by the
+caller if it was.
 If an error occurs,
 .Fn realpath
 returns
 .Dv NULL ,
 and if
 .Fa resolved_path
-is not
+was not
 .Dv NULL ,
-the array that it points to contains the pathname which caused the problem.
+the array that it points to contains the pathname which caused the
+problem.
 .Sh ERRORS
 The function
 .Fn realpath
@@ -107,6 +104,9 @@ for any of the errors specified for the library functions
 and
 .Xr getcwd 3 .
 .Sh SEE ALSO
+.Xr basename 3 ,
+.Xr dirname 3 ,
+.Xr free 3 ,
 .Xr getcwd 3
 .Sh STANDARDS
 The
@@ -118,15 +118,3 @@ The
 .Fn realpath
 function first appeared in
 .Bx 4.4 .
-.Sh CAVEATS
-This implementation of
-.Fn realpath
-differs slightly from the Solaris implementation.
-The
-.Bx 4.4
-version always returns absolute pathnames,
-whereas the Solaris implementation will,
-under certain circumstances, return a relative
-.Fa resolved_path
-when given a relative
-.Fa pathname .