original/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  2011-09-10 "" "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 The 4.4BSD, Linux and SUSv2 versions always return an absolute
 170 pathname.
 171 Solaris may return a relative pathname when the
 172 .I path
 173 argument is relative.
 174 The prototype of
 175 .BR realpath ()
 176 is given in \fI<unistd.h>\fP in libc4 and libc5,
 177 but in \fI<stdlib.h>\fP everywhere else.
 178 .SH BUGS
 179 The POSIX.1-2001 standard version of this function is broken by design,
 180 since it is impossible to determine a suitable size for the output buffer,
 181 .IR resolved_path .
 182 According to POSIX.1-2001 a buffer of size
 183 .B PATH_MAX
 184 suffices, but
 185 .B PATH_MAX
 186 need not be a defined constant, and may have to be obtained using
 187 .BR pathconf (3).
 188 And asking
 189 .BR pathconf (3)
 190 does not really help, since, on the one hand POSIX warns that
 191 the result of
 192 .BR pathconf (3)
 193 may be huge and unsuitable for mallocing memory,
 194 and on the other hand
 195 .BR pathconf (3)
 196 may return \-1 to signify that
 197 .B PATH_MAX
 198 is not bounded.
 199 The
 200 .I "resolved_path\ ==\ NULL"
 201 feature, not standardized in POSIX.1-2001,
 202 but standardized in POSIX.1-2008, allows this design problem to be avoided.
 203 .LP
 204 The libc4 and libc5 implementation contains a buffer overflow
 205 (fixed in libc-5.4.13).
 206 Thus, set-user-ID programs like
 207 .BR mount (8)
 208 need a private version.
 209 .SH "SEE ALSO"
 210 .BR readlink (2),
 211 .BR canonicalize_file_name (3),
 212 .BR getcwd (3),
 213 .BR pathconf (3),
 214 .BR sysconf (3)