man3/realpath.3

   1 .\" Copyright (C) 1999 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\" Permission is granted to copy and distribute modified versions of this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.  The author(s) may not
  16 .\" have taken the same level of care in the production of this manual,
  17 .\" which is licensed free of charge, as they might when working
  18 .\" professionally.
  19 .\"
  20 .\" Formatted or processed versions of this manual, if unaccompanied by
  21 .\" the source, must acknowledge the copyright and authors of this work.
  22 .\"
  23 .\" Rewritten old page, 990824, aeb@cwi.nl
  24 .\" 2004-12-14, mtk, added discussion of resolved_path == NULL
  25 .\"
  26 .TH REALPATH 3  2012-08-14 "" "Linux Programmer's Manual"
  27 .SH NAME
  28 realpath \- return the canonicalized absolute pathname
  29 .SH SYNOPSIS
  30 .nf
  31 .B #include <limits.h>
  32 .B #include <stdlib.h>
  33 .sp
  34 .BI "char *realpath(const char *" path ", char *" resolved_path );
  35 .fi
  36 .sp
  37 .in -4n
  38 Feature Test Macro Requirements for glibc (see
  39 .BR feature_test_macros (7)):
  40 .in
  41 .sp
  42 .BR realpath ():
  43 .ad l
  44 .RS 4
  45 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 ||
  46 _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  47 .RE
  48 .ad
  49 .SH DESCRIPTION
  50 .BR realpath ()
  51 expands all symbolic links and resolves references
  52 to
  53 .IR "/./" ", " "/../"
  54 and extra \(aq/\(aq
  55 characters in the null-terminated string named by
  56 .I path
  57 to produce a canonicalized absolute pathname.
  58 The resulting pathname is stored as a null-terminated string,
  59 up to a maximum of
  60 .B PATH_MAX
  61 bytes,
  62 in the buffer pointed to by
  63 .IR resolved_path .
  64 The resulting path will have no symbolic link,
  65 .I "/./"
  66 or
  67 .I "/../"
  68 components.
  69
  70 If
  71 .I resolved_path
  72 is specified as NULL, then
  73 .BR realpath ()
  74 uses
  75 .BR malloc (3)
  76 to allocate a buffer of up to
  77 .B PATH_MAX
  78 bytes to hold the resolved pathname,
  79 and returns a pointer to this buffer.
  80 The caller should deallocate this buffer using
  81 .BR free (3).
  82 .\" Even if we use resolved_path == NULL, then realpath() will still
  83 .\" return ENAMETOOLONG if the resolved pathname would exceed PATH_MAX
  84 .\" bytes -- MTK, Dec 04
  85 .\" .SH HISTORY
  86 .\" The
  87 .\" .BR realpath ()
  88 .\" function first appeared in 4.4BSD, contributed by Jan-Simon Pendry.
  89 .SH RETURN VALUE
  90 If there is no error,
  91 .BR realpath ()
  92 returns a pointer to the
  93 .IR resolved_path .
  94
  95 Otherwise it returns a NULL pointer, and the contents
  96 of the array
  97 .I resolved_path
  98 are undefined, and
  99 .I errno
 100 is set to indicate the error.
 101 .SH ERRORS
 102 .TP
 103 .B EACCES
 104 Read or search permission was denied for a component of the path prefix.
 105 .TP
 106 .B EINVAL
 107 .I path
 108 is NULL.
 109 .\" (In libc5 this would just cause a segfault.)
 110 (In glibc versions before 2.3,
 111 this error is also returned if
 112 .IR resolved_path
 113 is NULL.)
 114 .TP
 115 .B EIO
 116 An I/O error occurred while reading from the file system.
 117 .TP
 118 .B ELOOP
 119 Too many symbolic links were encountered in translating the pathname.
 120 .TP
 121 .B ENAMETOOLONG
 122 A component of a pathname exceeded
 123 .B NAME_MAX
 124 characters, or an entire pathname exceeded
 125 .B PATH_MAX
 126 characters.
 127 .TP
 128 .B ENOENT
 129 The named file does not exist.
 130 .TP
 131 .B ENOTDIR
 132 A component of the path prefix is not a directory.
 133 .SH VERSIONS
 134 On Linux this function appeared in libc 4.5.21.
 135 .SH CONFORMING TO
 136 4.4BSD, POSIX.1-2001.
 137
 138 POSIX.1-2001 says that the behavior if
 139 .I resolved_path
 140 is NULL is implementation-defined.
 141 POSIX.1-2008 specifies the behavior described in this page.
 142 .SH NOTES
 143 In 4.4BSD and Solaris the limit on the pathname length is
 144 .B MAXPATHLEN
 145 (found in \fI<sys/param.h>\fP).
 146 SUSv2 prescribes
 147 .B PATH_MAX
 148 and
 149 .BR NAME_MAX ,
 150 as found in \fI<limits.h>\fP or provided by the
 151 .BR pathconf (3)
 152 function.
 153 A typical source fragment would be
 154 .LP
 155 .in +4n
 156 .nf
 157 #ifdef PATH_MAX
 158   path_max = PATH_MAX;
 159 #else
 160   path_max = pathconf(path, _PC_PATH_MAX);
 161   if (path_max <= 0)
 162     path_max = 4096;
 163 #endif
 164 .fi
 165 .in
 166 .LP
 167 (But see the BUGS section.)
 168 .LP
 169 .\"     2012-05-05, According to Casper Dik, the statement about
 170 .\"     Solaris was not true at least as far back as 1997, and
 171 .\"     may never have been true.
 172 .\"
 173 .\" The 4.4BSD, Linux and SUSv2 versions always return an absolute
 174 .\" pathname.
 175 .\" Solaris may return a relative pathname when the
 176 .\" .I path
 177 .\" argument is relative.
 178 The prototype of
 179 .BR realpath ()
 180 is given in \fI<unistd.h>\fP in libc4 and libc5,
 181 but in \fI<stdlib.h>\fP everywhere else.
 182 .SH BUGS
 183 The POSIX.1-2001 standard version of this function is broken by design,
 184 since it is impossible to determine a suitable size for the output buffer,
 185 .IR resolved_path .
 186 According to POSIX.1-2001 a buffer of size
 187 .B PATH_MAX
 188 suffices, but
 189 .B PATH_MAX
 190 need not be a defined constant, and may have to be obtained using
 191 .BR pathconf (3).
 192 And asking
 193 .BR pathconf (3)
 194 does not really help, since, on the one hand POSIX warns that
 195 the result of
 196 .BR pathconf (3)
 197 may be huge and unsuitable for mallocing memory,
 198 and on the other hand
 199 .BR pathconf (3)
 200 may return \-1 to signify that
 201 .B PATH_MAX
 202 is not bounded.
 203 The
 204 .I "resolved_path\ ==\ NULL"
 205 feature, not standardized in POSIX.1-2001,
 206 but standardized in POSIX.1-2008, allows this design problem to be avoided.
 207 .LP
 208 The libc4 and libc5 implementation contained a buffer overflow
 209 (fixed in libc-5.4.13).
 210 Thus, set-user-ID programs like
 211 .BR mount (8)
 212 needed a private version.
 213 .SH SEE ALSO
 214 .BR readlink (2),
 215 .BR canonicalize_file_name (3),
 216 .BR getcwd (3),
 217 .BR pathconf (3),
 218 .BR sysconf (3)