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  2007-07-26 "" "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 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500
  44 .SH DESCRIPTION
  45 .BR realpath ()
  46 expands all symbolic links and resolves references
  47 to
  48 .IR '/./' ", " '/../'
  49 and extra
  50 .I '/'
  51 characters in the null terminated string named by
  52 .I path
  53 and stores the canonicalized absolute pathname in the buffer of size
  54 .B PATH_MAX
  55 named by
  56 .IR resolved_path .
  57 The resulting path will have no symbolic link,
  58 .I '/./'
  59 or
  60 .I '/../'
  61 components.
  62 .SH "RETURN VALUE"
  63 If there is no error,
  64 .BR realpath ()
  65 returns a pointer to the
  66 .IR resolved_path .
  67
  68 Otherwise it returns a NULL pointer, and the contents
  69 of the array
  70 .I resolved_path
  71 are undefined.
  72 The global variable
  73 .I errno
  74 is set to indicate the error.
  75 .SH ERRORS
  76 .TP
  77 .B EACCES
  78 Read or search permission was denied for a component of the path prefix.
  79 .TP
  80 .B EINVAL
  81 Either
  82 .I path
  83 or
  84 .I resolved_path
  85 is NULL. (In libc5 this would just cause a segfault.)
  86 But, see NOTES below.
  87 .TP
  88 .B EIO
  89 An I/O error occurred while reading from the file system.
  90 .TP
  91 .B ELOOP
  92 Too many symbolic links were encountered in translating the pathname.
  93 .TP
  94 .B ENAMETOOLONG
  95 A component of a pathname exceeded
  96 .B NAME_MAX
  97 characters, or an entire pathname exceeded
  98 .B PATH_MAX
  99 characters.
 100 .TP
 101 .B ENOENT
 102 The named file does not exist.
 103 .TP
 104 .B ENOTDIR
 105 A component of the path prefix is not a directory.
 106 .SH VERSIONS
 107 On Linux this function appeared in libc 4.5.21.
 108 .SH "CONFORMING TO"
 109 4.4BSD, POSIX.1-2001.
 110
 111 In 4.4BSD and Solaris the limit on the pathname length is
 112 .B MAXPATHLEN
 113 (found in \fI<sys/param.h>\fP).
 114 SUSv2 prescribes
 115 .BR PATH_MAX
 116 and
 117 .BR NAME_MAX ,
 118 as found in \fI<limits.h>\fP or provided by the
 119 .BR pathconf (3)
 120 function.
 121 A typical source fragment would be
 122 .LP
 123 .RS
 124 .nf
 125 #ifdef PATH_MAX
 126   path_max = PATH_MAX;
 127 #else
 128   path_max = pathconf(path, _PC_PATH_MAX);
 129   if (path_max <= 0)
 130     path_max = 4096;
 131 #endif
 132 .fi
 133 .RE
 134 (But see the BUGS section.)
 135 .LP
 136 The 4.4BSD, Linux and SUSv2 versions always return an absolute
 137 pathname.
 138 Solaris may return a relative pathname when the
 139 .I path
 140 argument is relative.
 141 The prototype of
 142 .BR realpath ()
 143 is given in \fI<unistd.h>\fP in libc4 and libc5,
 144 but in \fI<stdlib.h>\fP everywhere else.
 145 .SH NOTES
 146 The glibc implementation of
 147 .BR realpath ()
 148 provides a non-standard extension.
 149 If
 150 .I resolved_path
 151 is specified as NULL, then
 152 .BR realpath ()
 153 uses
 154 .BR malloc (3)
 155 to allocate a buffer of up to
 156 .B PATH_MAX
 157 bytes to hold the resolved pathname,
 158 and returns a pointer to this buffer.
 159 The caller should deallocate this buffer using
 160 .BR free (3).
 161 .\" Even if we use resolved_path == NULL, then realpath() will still
 162 .\" return ENAMETOOLONG if the resolved pathname would exceed PATH_MAX
 163 .\" bytes -- MTK, Dec 04
 164 .\" .SH HISTORY
 165 .\" The
 166 .\" .BR realpath ()
 167 .\" function first appeared in 4.4BSD, contributed by Jan-Simon Pendry.
 168 .SH BUGS
 169 Avoid using this function.
 170 It is broken by design since (unless
 171 using the non-standard
 172 .I "resolved_path\ ==\ NULL"
 173 feature) it is
 174 impossible to determine a suitable size for the output buffer,
 175 .IR resolved_path .
 176 According to POSIX a buffer of size
 177 .B PATH_MAX
 178 suffices, but
 179 .B PATH_MAX
 180 need not be a defined constant, and may have to be obtained using
 181 .BR pathconf (3).
 182 And asking
 183 .BR pathconf (3)
 184 does not really help, since on the one hand POSIX warns that
 185 the result of
 186 .BR pathconf (3)
 187 may be huge and unsuitable for mallocing memory.
 188 And on the other
 189 hand
 190 .BR pathconf (3)
 191 may return \-1 to signify that
 192 .B PATH_MAX
 193 is not bounded.
 194 .LP
 195 The libc4 and libc5 implementation contains a buffer overflow
 196 (fixed in libc-5.4.13).
 197 Thus, set-user-ID programs like mount need a private version.
 198 .SH "SEE ALSO"
 199 .BR readlink (2),
 200 .BR canonicalize_file_name (3),
 201 .BR getcwd (3),
 202 .BR pathconf (3),
 203 .BR sysconf (3)