1  .\" Copyright (c) 1994
  2  .\"	The Regents of the University of California.  All rights reserved.
  3  .\"
  4  .\" This code is derived from software contributed to Berkeley by
  5  .\" Jan-Simon Pendry.
  6  .\"
  7  .\" Redistribution and use in source and binary forms, with or without
  8  .\" modification, are permitted provided that the following conditions
  9  .\" are met:
 10  .\" 1. Redistributions of source code must retain the above copyright
 11  .\"    notice, this list of conditions and the following disclaimer.
 12  .\" 2. Redistributions in binary form must reproduce the above copyright
 13  .\"    notice, this list of conditions and the following disclaimer in the
 14  .\"    documentation and/or other materials provided with the distribution.
 15  .\" 4. Neither the name of the University nor the names of its contributors
 16  .\"    may be used to endorse or promote products derived from this software
 17  .\"    without specific prior written permission.
 18  .\"
 19  .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
 20  .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 21  .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 22  .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
 23  .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 24  .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 25  .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 26  .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 27  .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 28  .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 29  .\" SUCH DAMAGE.
 30  .\"
 31  .\"     @(#)realpath.3	8.2 (Berkeley) 2/16/94
 32  .\" $FreeBSD: src/lib/libc/stdlib/realpath.3,v 1.14 2007/01/09 00:28:10 imp Exp $
 33  .\"
 34  .Dd April 5, 2008
 35  .Dt REALPATH 3
 36  .Os
 37  .Sh NAME
 38  .Nm realpath
 39  .Nd returns the canonicalized absolute pathname
 40  .\" .Sh LIBRARY
 41  .\" .Lb libc
 42  .Sh SYNOPSIS
 43  .In stdlib.h
 44  .Ft "char *"
 45  .Fo realpath
 46  .Fa "const char *restrict file_name"
 47  .Fa "char *restrict resolved_name"
 48  .Fc
 49  .Sh DESCRIPTION
 50  The
 51  .Fn realpath
 52  function resolves all symbolic links, extra
 53  .Dq /
 54  characters, and references to
 55  .Pa /./
 56  and
 57  .Pa /../
 58  in
 59  .Fa file_name .
 60  If the
 61  .Fa resolved_name
 62  argument
 63  is non-NULL, the resulting absolute pathname is copied there (it
 64  .Em must
 65  refer to a buffer capable of storing at least
 66  .Dv PATH_MAX
 67  characters).
 68  .Pp
 69  As a permitted extension to the standard, if
 70  .Fa resolved_name
 71  is NULL, 
 72  memory is allocated for the resulting absolute pathname, and is returned by
 73  .Fn realpath .
 74  This memory should be freed by a call to
 75  .Xr free 3
 76  when no longer needed.
 77  .Pp
 78  The
 79  .Fn realpath
 80  function will resolve both absolute and relative paths
 81  and return the absolute pathname corresponding to
 82  .Fa file_name .
 83  All components of
 84  .Fa file_name
 85  must exist when
 86  .Fn realpath
 87  is called.
 88  .Sh "RETURN VALUES"
 89  On success, the
 90  .Fn realpath
 91  function returns the address of the resulting absolute pathname, which is
 92  .Fa resolved_name
 93  if it was non-NULL, or the address of newly allocated memory.
 94  If an error occurs,
 95  .Fn realpath
 96  returns
 97  .Dv NULL .
 98  If
 99  .Fa resolved_name
100  was non-NULL, it will
101  contain the pathname which caused the problem.
102  .Sh VARIANTS
103  Defining 
104  .Dv _DARWIN_C_SOURCE
105  or
106  .Dv _DARWIN_BETTER_REALPATH
107  before including stdlib.h will cause the provided implementation of
108  .Fn realpath
109  to use F_GETPATH from
110  .Xr fcntl 2
111  to discover the path.
112  .Sh ERRORS
113  The function
114  .Fn realpath
115  may fail and set the external variable
116  .Va errno
117  for any of the errors specified for the library functions
118  .Xr alloca 3 ,
119  .Xr getattrlist 2 ,
120  .Xr getcwd 3 ,
121  .Xr lstat 2 ,
122  .Xr readlink 2 ,
123  .Xr stat 2 ,
124  and
125  .Xr strdup 3 .
126  .\" .Sh CAVEATS
127  .\" This implementation of
128  .\" .Fn realpath
129  .\" differs slightly from the Solaris implementation.
130  .\" The
131  .\" .Bx 4.4
132  .\" version always returns absolute pathnames,
133  .\" whereas the Solaris implementation will,
134  .\" under certain circumstances, return a relative
135  .\" .Fa resolved_name
136  .\" when given a relative
137  .\" .Fa file_name .
138  .Sh LEGACY SYNOPSIS
139  .Fd #include <sys/param.h>
140  .Fd #include <stdlib.h>
141  .Pp
142  The include file
143  .In sys/param.h
144  is necessary.
145  .Sh LEGACY DESCRIPTION
146  In legacy mode,
147  the last component of
148  .Fa file_name
149  does not need to exist when
150  .Fn realpath
151  is called.
152  .Sh "SEE ALSO"
153  .Xr free 3 ,
154  .Xr getcwd 3 ,
155  .Xr compat 5
156  .Sh HISTORY
157  The
158  .Fn realpath
159  function first appeared in
160  .Bx 4.4 .