lib/libc/gen/realpath.3

   1 .\"     $NetBSD: realpath.3,v 1.18 2013/05/24 09:35:11 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1994
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to Berkeley by
   7 .\" Jan-Simon Pendry.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\" 3. Neither the name of the University nor the names of its contributors
  18 .\"    may be used to endorse or promote products derived from this software
  19 .\"    without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\"
  33 .\"     from: @(#)realpath.3    8.2 (Berkeley) 2/16/94
  34 .\"
  35 .Dd May 24, 2013
  36 .Dt REALPATH 3
  37 .Os
  38 .Sh NAME
  39 .Nm realpath
  40 .Nd returns the canonicalized absolute pathname
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In sys/param.h
  45 .In stdlib.h
  46 .Ft "char *"
  47 .Fn realpath "const char * restrict pathname" "char * restrict resolvedname"
  48 .Sh DESCRIPTION
  49 The
  50 .Fn realpath
  51 function resolves all symbolic links, extra
  52 .Dq /
  53 characters and references to
  54 .Pa /./
  55 and
  56 .Pa /../
  57 in
  58 .Fa pathname ,
  59 and copies the resulting absolute pathname into
  60 the memory referenced by
  61 .Fa resolvedname .
  62 The
  63 .Fa resolvedname
  64 argument
  65 .Em must
  66 refer to a buffer capable of storing at least
  67 .Dv MAXPATHLEN
  68 characters, or be
  69 .Dv NULL .
  70 .Pp
  71 The
  72 .Fn realpath
  73 function will resolve both absolute and relative paths
  74 and return the absolute pathname corresponding to
  75 .Fa pathname .
  76 .Sh RETURN VALUES
  77 If
  78 .Fa resolvedname
  79 is
  80 .Dv NULL ,
  81 it will be allocated and the returned pointer can be deallocated using
  82 .Xr free 3 .
  83 The
  84 .Fn realpath
  85 function returns
  86 .Fa resolvedname
  87 on success.
  88 If an error occurs,
  89 .Fn realpath
  90 returns
  91 .Dv NULL ,
  92 and
  93 .Fa resolvedname
  94 was not allocated by
  95 .Fn realpath ,
  96 it will contain the pathname which caused the problem.
  97 .Sh ERRORS
  98 The function
  99 .Fn realpath
 100 may fail and set the external variable
 101 .Va errno
 102 for any of the errors specified for the library functions
 103 .\" First sorted by section, then by name.
 104 .Xr lstat 2 ,
 105 .Xr readlink 2 ,
 106 .Xr getcwd 3
 107 and
 108 .Xr malloc 3 .
 109 .Pp
 110 In addition, the following errors may be reported:
 111 .Bl -tag -width Er
 112 .It Bq Er EINVAL
 113 The value of the
 114 .Fa pathname
 115 argument is
 116 .Dv NULL .
 117 .It Bq Er ELOOP
 118 Too many symbolic links were encountered in translating the
 119 .Fa pathname .
 120 .It Bq Er ENAMETOOLONG
 121 The resulting absolute pathname exceeds
 122 .Dv MAXPATHLEN
 123 characters.
 124 .It Bq Er ENOENT
 125 The value of the
 126 .Fa pathname
 127 argument is an empty string;
 128 or a symbolic link to an empty string is encountered.
 129 .It Bq Er ENOTDIR
 130 A component of the path prefix is not a directory.
 131 .El
 132 .Sh SEE ALSO
 133 .Xr getcwd 3
 134 .Sh STANDARDS
 135 .Fn realpath
 136 first appeared in
 137 .St -xpg4.2
 138 and is part of
 139 .St -p1003.1-2001 .
 140 .Sh HISTORY
 141 The
 142 .Fn realpath
 143 function call first appeared in
 144 .Bx 4.4 .
 145 In
 146 .Nx 7.0
 147 the function was updated to accept a
 148 .Dv NULL
 149 pointer for the
 150 .Fa resolvedname
 151 argument.
 152 .Sh BUGS
 153 This implementation of
 154 .Fn realpath
 155 differs slightly from the Solaris implementation.
 156 The
 157 .Bx 4.4
 158 version always returns absolute pathnames,
 159 whereas the Solaris implementation will,
 160 under certain circumstances, return a relative
 161 .Fa resolvedname
 162 when given a relative
 163 .Fa pathname .