Libc-1439.100.3.tar.gz

[apple/libc.git] / stdlib / FreeBSD / realpath.3

diff --git a/stdlib/FreeBSD/realpath.3 b/stdlib/FreeBSD/realpath.3
index dc6ba9abe92c5d9a6805c444521b6036bfe74832..07e9dcc95546bf3ba50674eeb3f7e554421f77af 100644 (file)
--- a/stdlib/FreeBSD/realpath.3
+++ b/stdlib/FreeBSD/realpath.3
@@ -31,88 +31,128 @@
 .\"     @(#)realpath.3 8.2 (Berkeley) 2/16/94
 .\" $FreeBSD: src/lib/libc/stdlib/realpath.3,v 1.14 2007/01/09 00:28:10 imp Exp $
 .\"
-.Dd February 16, 1994
+.Dd April 5, 2008
 .Dt REALPATH 3
 .Os
 .Sh NAME
 .Nm realpath
 .Nd returns the canonicalized absolute pathname
-.Sh LIBRARY
-.Lb libc
+.\" .Sh LIBRARY
+.\" .Lb libc
 .Sh SYNOPSIS
-.In sys/param.h
 .In stdlib.h
 .Ft "char *"
-.Fn realpath "const char *pathname" "char resolved_path[PATH_MAX]"
+.Fo realpath
+.Fa "const char *restrict file_name"
+.Fa "char *restrict resolved_name"
+.Fc
 .Sh DESCRIPTION
 The
 .Fn realpath
 function resolves all symbolic links, extra
 .Dq /
-characters and references to
+characters, and references to
 .Pa /./
 and
 .Pa /../
 in
-.Fa pathname ,
-and copies the resulting absolute pathname into
-the memory referenced by
-.Fa resolved_path .
-The
-.Fa resolved_path
+.Fa file_name .
+If the
+.Fa resolved_name
 argument
+is non-NULL, the resulting absolute pathname is copied there (it
 .Em must
 refer to a buffer capable of storing at least
 .Dv PATH_MAX
-characters.
+characters).
+.Pp
+As a permitted extension to the standard, if
+.Fa resolved_name
+is NULL, 
+memory is allocated for the resulting absolute pathname, and is returned by
+.Fn realpath .
+This memory should be freed by a call to
+.Xr free 3
+when no longer needed.
 .Pp
 The
 .Fn realpath
 function will resolve both absolute and relative paths
 and return the absolute pathname corresponding to
-.Fa pathname .
-All but the last component of
-.Fa pathname
+.Fa file_name .
+All components of
+.Fa file_name
 must exist when
 .Fn realpath
 is called.
 .Sh "RETURN VALUES"
-The
+On success, the
 .Fn realpath
-function returns
-.Fa resolved_path
-on success.
+function returns the address of the resulting absolute pathname, which is
+.Fa resolved_name
+if it was non-NULL, or the address of newly allocated memory.
 If an error occurs,
 .Fn realpath
 returns
-.Dv NULL ,
-and
-.Fa resolved_path
-contains the pathname which caused the problem.
+.Dv NULL .
+If
+.Fa resolved_name
+was non-NULL, it will
+contain the pathname which caused the problem.
+.Sh VARIANTS
+Defining 
+.Dv _DARWIN_C_SOURCE
+or
+.Dv _DARWIN_BETTER_REALPATH
+before including stdlib.h will cause the provided implementation of
+.Fn realpath
+to use F_GETPATH from
+.Xr fcntl 2
+to discover the path.
 .Sh ERRORS
 The function
 .Fn realpath
 may fail and set the external variable
 .Va errno
 for any of the errors specified for the library functions
+.Xr alloca 3 ,
+.Xr getattrlist 2 ,
+.Xr getcwd 3 ,
 .Xr lstat 2 ,
-.Xr readlink 2
+.Xr readlink 2 ,
+.Xr stat 2 ,
 and
-.Xr getcwd 3 .
-.Sh CAVEATS
-This implementation of
+.Xr strdup 3 .
+.\" .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_name
+.\" when given a relative
+.\" .Fa file_name .
+.Sh LEGACY SYNOPSIS
+.Fd #include <sys/param.h>
+.Fd #include <stdlib.h>
+.Pp
+The include file
+.In sys/param.h
+is necessary.
+.Sh LEGACY DESCRIPTION
+In legacy mode,
+the last component of
+.Fa file_name
+does not need to exist when
 .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 .
+is called.
 .Sh "SEE ALSO"
-.Xr getcwd 3
+.Xr free 3 ,
+.Xr getcwd 3 ,
+.Xr compat 5
 .Sh HISTORY
 The
 .Fn realpath