git: 1aecb32021ce - main - realpath: Improve manual page

The branch main has been updated by des:

URL: https://cgit.FreeBSD.org/src/commit/?id=1aecb32021ce46d812db36b9037cdc6f423575f9

commit 1aecb32021ce46d812db36b9037cdc6f423575f9
Author:     Dag-Erling Smørgrav <des@FreeBSD.org>
AuthorDate: 2026-03-19 01:26:21 +0000
Commit:     Dag-Erling Smørgrav <des@FreeBSD.org>
CommitDate: 2026-03-19 01:26:34 +0000

    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
---
 lib/libc/stdlib/realpath.3 | 36 ++++++++++++------------------------
 1 file 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 .