man3/realpath.3

   1 '\" t
   2 .\" Copyright (C) 1999 Andries Brouwer (aeb@cwi.nl)
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" Rewritten old page, 990824, aeb@cwi.nl
   7 .\" 2004-12-14, mtk, added discussion of resolved_path == NULL
   8 .\"
   9 .TH realpath 3 (date) "Linux man-pages (unreleased)"
  10 .SH NAME
  11 realpath \- return the canonicalized absolute pathname
  12 .SH LIBRARY
  13 Standard C library
  14 .RI ( libc ", " \-lc )
  15 .SH SYNOPSIS
  16 .nf
  17 .B #include <limits.h>
  18 .B #include <stdlib.h>
  19 .PP
  20 .BI "char *realpath(const char *restrict " path ,
  21 .BI "               char *restrict " resolved_path );
  22 .fi
  23 .PP
  24 .RS -4
  25 Feature Test Macro Requirements for glibc (see
  26 .BR feature_test_macros (7)):
  27 .RE
  28 .PP
  29 .BR realpath ():
  30 .nf
  31     _XOPEN_SOURCE >= 500
  32 .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
  33         || /* glibc >= 2.19: */ _DEFAULT_SOURCE
  34         || /* glibc <= 2.19: */ _BSD_SOURCE
  35 .fi
  36 .SH DESCRIPTION
  37 .BR realpath ()
  38 expands all symbolic links and resolves references
  39 to
  40 .IR "/./" ", " "/../"
  41 and extra \[aq]/\[aq]
  42 characters in the null-terminated string named by
  43 .I path
  44 to produce a canonicalized absolute pathname.
  45 The resulting pathname is stored as a null-terminated string,
  46 up to a maximum of
  47 .B PATH_MAX
  48 bytes,
  49 in the buffer pointed to by
  50 .IR resolved_path .
  51 The resulting path will have no symbolic link,
  52 .I "/./"
  53 or
  54 .I "/../"
  55 components.
  56 .PP
  57 If
  58 .I resolved_path
  59 is specified as NULL, then
  60 .BR realpath ()
  61 uses
  62 .BR malloc (3)
  63 to allocate a buffer of up to
  64 .B PATH_MAX
  65 bytes to hold the resolved pathname,
  66 and returns a pointer to this buffer.
  67 The caller should deallocate this buffer using
  68 .BR free (3).
  69 .\" Even if we use resolved_path == NULL, then realpath() will still
  70 .\" return ENAMETOOLONG if the resolved pathname would exceed PATH_MAX
  71 .\" bytes -- MTK, Dec 04
  72 .SH RETURN VALUE
  73 If there is no error,
  74 .BR realpath ()
  75 returns a pointer to the
  76 .IR resolved_path .
  77 .PP
  78 Otherwise, it returns NULL, the contents
  79 of the array
  80 .I resolved_path
  81 are undefined, and
  82 .I errno
  83 is set to indicate the error.
  84 .SH ERRORS
  85 .TP
  86 .B EACCES
  87 Read or search permission was denied for a component of the path prefix.
  88 .TP
  89 .B EINVAL
  90 .I path
  91 is NULL.
  92 .\" (In libc5 this would just cause a segfault.)
  93 (Before glibc 2.3,
  94 this error is also returned if
  95 .I resolved_path
  96 is NULL.)
  97 .TP
  98 .B EIO
  99 An I/O error occurred while reading from the filesystem.
 100 .TP
 101 .B ELOOP
 102 Too many symbolic links were encountered in translating the pathname.
 103 .TP
 104 .B ENAMETOOLONG
 105 A component of a pathname exceeded
 106 .B NAME_MAX
 107 characters, or an entire pathname exceeded
 108 .B PATH_MAX
 109 characters.
 110 .TP
 111 .B ENOENT
 112 The named file does not exist.
 113 .TP
 114 .B ENOMEM
 115 Out of memory.
 116 .TP
 117 .B ENOTDIR
 118 A component of the path prefix is not a directory.
 119 .SH ATTRIBUTES
 120 For an explanation of the terms used in this section, see
 121 .BR attributes (7).
 122 .ad l
 123 .nh
 124 .TS
 125 allbox;
 126 lbx lb lb
 127 l l l.
 128 Interface       Attribute       Value
 129 T{
 130 .BR realpath ()
 131 T}      Thread safety   MT-Safe
 132 .TE
 133 .hy
 134 .ad
 135 .sp 1
 136 .SH VERSIONS
 137 .SS GNU extensions
 138 If the call fails with either
 139 .B EACCES
 140 or
 141 .B ENOENT
 142 and
 143 .I resolved_path
 144 is not NULL, then the prefix of
 145 .I path
 146 that is not readable or does not exist is returned in
 147 .IR resolved_path .
 148 .SH STANDARDS
 149 POSIX.1-2008.
 150 .SH HISTORY
 151 4.4BSD, POSIX.1-2001, Solaris.
 152 .PP
 153 POSIX.1-2001 says that the behavior if
 154 .I resolved_path
 155 is NULL is implementation-defined.
 156 POSIX.1-2008 specifies the behavior described in this page.
 157 .PP
 158 In 4.4BSD and Solaris, the limit on the pathname length is
 159 .B MAXPATHLEN
 160 (found in \fI<sys/param.h>\fP).
 161 SUSv2 prescribes
 162 .B PATH_MAX
 163 and
 164 .BR NAME_MAX ,
 165 as found in \fI<limits.h>\fP or provided by the
 166 .BR pathconf (3)
 167 function.
 168 A typical source fragment would be
 169 .PP
 170 .in +4n
 171 .EX
 172 #ifdef PATH_MAX
 173   path_max = PATH_MAX;
 174 #else
 175   path_max = pathconf(path, _PC_PATH_MAX);
 176   if (path_max <= 0)
 177     path_max = 4096;
 178 #endif
 179 .EE
 180 .in
 181 .PP
 182 (But see the BUGS section.)
 183 .\".PP
 184 .\"     2012-05-05, According to Casper Dik, the statement about
 185 .\"     Solaris was not true at least as far back as 1997, and
 186 .\"     may never have been true.
 187 .\"
 188 .\" The 4.4BSD, Linux and SUSv2 versions always return an absolute
 189 .\" pathname.
 190 .\" Solaris may return a relative pathname when the
 191 .\" .I path
 192 .\" argument is relative.
 193 .\" The prototype of
 194 .\" .BR realpath ()
 195 .\" is given in \fI<unistd.h>\fP in libc4 and libc5,
 196 .\" but in \fI<stdlib.h>\fP everywhere else.
 197 .SH BUGS
 198 The POSIX.1-2001 standard version of this function is broken by design,
 199 since it is impossible to determine a suitable size for the output buffer,
 200 .IR resolved_path .
 201 According to POSIX.1-2001 a buffer of size
 202 .B PATH_MAX
 203 suffices, but
 204 .B PATH_MAX
 205 need not be a defined constant, and may have to be obtained using
 206 .BR pathconf (3).
 207 And asking
 208 .BR pathconf (3)
 209 does not really help, since, on the one hand POSIX warns that
 210 the result of
 211 .BR pathconf (3)
 212 may be huge and unsuitable for mallocing memory,
 213 and on the other hand
 214 .BR pathconf (3)
 215 may return \-1 to signify that
 216 .B PATH_MAX
 217 is not bounded.
 218 The
 219 .I "resolved_path\ ==\ NULL"
 220 feature, not standardized in POSIX.1-2001,
 221 but standardized in POSIX.1-2008, allows this design problem to be avoided.
 222 .\" .LP
 223 .\" The libc4 and libc5 implementation contained a buffer overflow
 224 .\" (fixed in libc-5.4.13).
 225 .\" Thus, set-user-ID programs like
 226 .\" .BR mount (8)
 227 .\" needed a private version.
 228 .SH SEE ALSO
 229 .BR realpath (1),
 230 .BR readlink (2),
 231 .BR canonicalize_file_name (3),
 232 .BR getcwd (3),
 233 .BR pathconf (3),
 234 .BR sysconf (3)