stdlib/FreeBSD/realpath.3.patch

   1 --- realpath.3.orig     2008-04-05 00:03:06.000000000 -0700
   2 +++ realpath.3  2008-04-05 17:42:41.000000000 -0700
   3 @@ -35,63 +35,73 @@
   4  .\"     @(#)realpath.3 8.2 (Berkeley) 2/16/94
   5  .\" $FreeBSD: src/lib/libc/stdlib/realpath.3,v 1.13 2003/03/27 20:48:53 fjoe Exp $
   6  .\"
   7 -.Dd February 16, 1994
   8 +.Dd April 5, 2008
   9  .Dt REALPATH 3
  10  .Os
  11  .Sh NAME
  12  .Nm realpath
  13  .Nd returns the canonicalized absolute pathname
  14 -.Sh LIBRARY
  15 -.Lb libc
  16 +.\" .Sh LIBRARY
  17 +.\" .Lb libc
  18  .Sh SYNOPSIS
  19 -.In sys/param.h
  20  .In stdlib.h
  21  .Ft "char *"
  22 -.Fn realpath "const char *pathname" "char resolved_path[PATH_MAX]"
  23 +.Fo realpath
  24 +.Fa "const char *restrict file_name"
  25 +.Fa "char *restrict resolved_name"
  26 +.Fc
  27  .Sh DESCRIPTION
  28  The
  29  .Fn realpath
  30  function resolves all symbolic links, extra
  31  .Dq /
  32 -characters and references to
  33 +characters, and references to
  34  .Pa /./
  35  and
  36  .Pa /../
  37  in
  38 -.Fa pathname ,
  39 -and copies the resulting absolute pathname into
  40 -the memory referenced by
  41 -.Fa resolved_path .
  42 -The
  43 -.Fa resolved_path
  44 +.Fa file_name .
  45 +If the
  46 +.Fa resolved_name
  47  argument
  48 +is non-NULL, the resulting absolute pathname is copied there (it
  49  .Em must
  50  refer to a buffer capable of storing at least
  51  .Dv PATH_MAX
  52 -characters.
  53 +characters).
  54 +.Pp
  55 +As a permitted extension to the standard, if
  56 +.Fa resolved_name
  57 +is NULL,
  58 +memory is allocated for the resulting absolute pathname, and is returned by
  59 +.Fn realpath .
  60 +This memory should be freed by a call to
  61 +.Xr free 3
  62 +when no longer needed.
  63  .Pp
  64  The
  65  .Fn realpath
  66  function will resolve both absolute and relative paths
  67  and return the absolute pathname corresponding to
  68 -.Fa pathname .
  69 -All but the last component of
  70 -.Fa pathname
  71 +.Fa file_name .
  72 +All components of
  73 +.Fa file_name
  74  must exist when
  75  .Fn realpath
  76  is called.
  77  .Sh "RETURN VALUES"
  78 -The
  79 +On success, the
  80  .Fn realpath
  81 -function returns
  82 -.Fa resolved_path
  83 -on success.
  84 +function returns the address of the resulting absolute pathname, which is
  85 +.Fa resolved_name
  86 +if it was non-NULL, or the address of newly allocated memory.
  87  If an error occurs,
  88  .Fn realpath
  89  returns
  90 -.Dv NULL ,
  91 -and
  92 -.Fa resolved_path
  93 +.Dv NULL .
  94 +If
  95 +.Fa resolved_name
  96 +was non-NULL, it will
  97  contains the pathname which caused the problem.
  98  .Sh ERRORS
  99  The function
 100 @@ -99,24 +109,44 @@
 101  may fail and set the external variable
 102  .Va errno
 103  for any of the errors specified for the library functions
 104 +.Xr alloca 3 ,
 105 +.Xr getattrlist 2 ,
 106 +.Xr getcwd 3 ,
 107  .Xr lstat 2 ,
 108 -.Xr readlink 2
 109 +.Xr readlink 2 ,
 110 +.Xr stat 2 ,
 111  and
 112 -.Xr getcwd 3 .
 113 -.Sh CAVEATS
 114 -This implementation of
 115 +.Xr strdup 3 .
 116 +.\" .Sh CAVEATS
 117 +.\" This implementation of
 118 +.\" .Fn realpath
 119 +.\" differs slightly from the Solaris implementation.
 120 +.\" The
 121 +.\" .Bx 4.4
 122 +.\" version always returns absolute pathnames,
 123 +.\" whereas the Solaris implementation will,
 124 +.\" under certain circumstances, return a relative
 125 +.\" .Fa resolved_name
 126 +.\" when given a relative
 127 +.\" .Fa file_name .
 128 +.Sh LEGACY SYNOPSIS
 129 +.Fd #include <sys/param.h>
 130 +.Fd #include <stdlib.h>
 131 +.Pp
 132 +The include file
 133 +.In sys/param.h
 134 +is necessary.
 135 +.Sh LEGACY DESCRIPTION
 136 +In legacy mode,
 137 +the last component of
 138 +.Fa file_name
 139 +does not need to exist when
 140  .Fn realpath
 141 -differs slightly from the Solaris implementation.
 142 -The
 143 -.Bx 4.4
 144 -version always returns absolute pathnames,
 145 -whereas the Solaris implementation will,
 146 -under certain circumstances, return a relative
 147 -.Fa resolved_path
 148 -when given a relative
 149 -.Fa pathname .
 150 +is called.
 151  .Sh "SEE ALSO"
 152 -.Xr getcwd 3
 153 +.Xr free 3 ,
 154 +.Xr getcwd 3 ,
 155 +.Xr compat 5
 156  .Sh HISTORY
 157  The
 158  .Fn realpath