stdlib/realpath.3

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