man2/readlink.2

   1 .\" Copyright (c) 1983, 1991 The Regents of the University of California.
   2 .\" And Copyright (C) 2011 Guillem Jover <guillem@hadrons.org>
   3 .\" And Copyright (C) 2006, 2014 Michael Kerrisk
   4 .\" All rights reserved.
   5 .\"
   6 .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. All advertising materials mentioning features or use of this software
  16 .\"    must display the following acknowledgement:
  17 .\"     This product includes software developed by the University of
  18 .\"     California, Berkeley and its contributors.
  19 .\" 4. Neither the name of the University nor the names of its contributors
  20 .\"    may be used to endorse or promote products derived from this software
  21 .\"    without specific prior written permission.
  22 .\"
  23 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  26 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  33 .\" SUCH DAMAGE.
  34 .\" %%%LICENSE_END
  35 .\"
  36 .\"     @(#)readlink.2  6.8 (Berkeley) 3/10/91
  37 .\"
  38 .\" Modified Sat Jul 24 00:10:21 1993 by Rik Faith (faith@cs.unc.edu)
  39 .\" Modified Tue Jul  9 23:55:17 1996 by aeb
  40 .\" Modified Fri Jan 24 00:26:00 1997 by aeb
  41 .\" 2011-09-20, Guillem Jover <guillem@hadrons.org>:
  42 .\"     Added text on dynamically allocating buffer + example program
  43 .\"
  44 .TH READLINK 2 2020-06-09 "Linux" "Linux Programmer's Manual"
  45 .SH NAME
  46 readlink, readlinkat \- read value of a symbolic link
  47 .SH SYNOPSIS
  48 .nf
  49 .B #include <unistd.h>
  50 .PP
  51 .BI "ssize_t readlink(const char *" pathname ", char *" buf \
  52 ", size_t " bufsiz );
  53
  54 .BR "#include <fcntl.h>           " "/* Definition of AT_* constants */"
  55 .B #include <unistd.h>
  56 .PP
  57 .BI "ssize_t readlinkat(int " dirfd ", const char *" pathname ,
  58 .BI "                   char *" buf ", size_t " bufsiz );
  59 .PP
  60 .fi
  61 .in -4n
  62 Feature Test Macro Requirements for glibc (see
  63 .BR feature_test_macros (7)):
  64 .in
  65 .PP
  66 .ad l
  67 .BR readlink ():
  68 .RS 4
  69 _XOPEN_SOURCE\ >=\ 500 || _POSIX_C_SOURCE\ >=\ 200112L
  70 .\"    || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  71     || /* Glibc versions <= 2.19: */ _BSD_SOURCE
  72 .RE
  73 .PP
  74 .BR readlinkat ():
  75 .PD 0
  76 .ad l
  77 .RS 4
  78 .TP 4
  79 Since glibc 2.10:
  80 _POSIX_C_SOURCE\ >=\ 200809L
  81 .TP
  82 Before glibc 2.10:
  83 _ATFILE_SOURCE
  84 .RE
  85 .ad b
  86 .PD
  87 .SH DESCRIPTION
  88 .BR readlink ()
  89 places the contents of the symbolic link
  90 .I pathname
  91 in the buffer
  92 .IR buf ,
  93 which has size
  94 .IR bufsiz .
  95 .BR readlink ()
  96 does not append a null byte to
  97 .IR buf .
  98 It will (silently) truncate the contents (to a length of
  99 .I bufsiz
 100 characters), in case the buffer is too small to hold all of the contents.
 101 .SS readlinkat()
 102 The
 103 .BR readlinkat ()
 104 system call operates in exactly the same way as
 105 .BR readlink (),
 106 except for the differences described here.
 107 .PP
 108 If the pathname given in
 109 .I pathname
 110 is relative, then it is interpreted relative to the directory
 111 referred to by the file descriptor
 112 .I dirfd
 113 (rather than relative to the current working directory of
 114 the calling process, as is done by
 115 .BR readlink ()
 116 for a relative pathname).
 117 .PP
 118 If
 119 .I pathname
 120 is relative and
 121 .I dirfd
 122 is the special value
 123 .BR AT_FDCWD ,
 124 then
 125 .I pathname
 126 is interpreted relative to the current working
 127 directory of the calling process (like
 128 .BR readlink ()).
 129 .PP
 130 If
 131 .I pathname
 132 is absolute, then
 133 .I dirfd
 134 is ignored.
 135 .PP
 136 Since Linux 2.6.39,
 137 .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
 138 .I pathname
 139 can be an empty string,
 140 in which case the call operates on the symbolic link referred to by
 141 .IR dirfd
 142 (which should have been obtained using
 143 .BR open (2)
 144 with the
 145 .B O_PATH
 146 and
 147 .B O_NOFOLLOW
 148 flags).
 149 .PP
 150 See
 151 .BR openat (2)
 152 for an explanation of the need for
 153 .BR readlinkat ().
 154 .SH RETURN VALUE
 155 On success, these calls return the number of bytes placed in
 156 .IR buf .
 157 (If the returned value equals
 158 .IR bufsiz ,
 159 then truncation may have occurred.)
 160 On error, \-1 is returned and
 161 .I errno
 162 is set to indicate the error.
 163 .SH ERRORS
 164 .TP
 165 .B EACCES
 166 Search permission is denied for a component of the path prefix.
 167 (See also
 168 .BR path_resolution (7).)
 169 .TP
 170 .B EFAULT
 171 .I buf
 172 extends outside the process's allocated address space.
 173 .TP
 174 .B EINVAL
 175 .I bufsiz
 176 is not positive.
 177 .\" At the glibc level, bufsiz is unsigned, so this error can only occur
 178 .\" if bufsiz==0.  However, the in the kernel syscall, bufsiz is signed,
 179 .\" and this error can also occur if bufsiz < 0.
 180 .\" See: http://thread.gmane.org/gmane.linux.man/380
 181 .\" Subject: [patch 0/3] [RFC] kernel/glibc mismatch of "readlink" syscall?
 182 .TP
 183 .B EINVAL
 184 The named file (i.e., the final filename component of
 185 .IR pathname )
 186 is not a symbolic link.
 187 .TP
 188 .B EIO
 189 An I/O error occurred while reading from the filesystem.
 190 .TP
 191 .B ELOOP
 192 Too many symbolic links were encountered in translating the pathname.
 193 .TP
 194 .B ENAMETOOLONG
 195 A pathname, or a component of a pathname, was too long.
 196 .TP
 197 .B ENOENT
 198 The named file does not exist.
 199 .TP
 200 .B ENOMEM
 201 Insufficient kernel memory was available.
 202 .TP
 203 .B ENOTDIR
 204 A component of the path prefix is not a directory.
 205 .PP
 206 The following additional errors can occur for
 207 .BR readlinkat ():
 208 .TP
 209 .B EBADF
 210 .I dirfd
 211 is not a valid file descriptor.
 212 .TP
 213 .B ENOTDIR
 214 .I pathname
 215 is relative and
 216 .I dirfd
 217 is a file descriptor referring to a file other than a directory.
 218 .SH VERSIONS
 219 .BR readlinkat ()
 220 was added to Linux in kernel 2.6.16;
 221 library support was added to glibc in version 2.4.
 222 .SH CONFORMING TO
 223 .BR readlink ():
 224 4.4BSD
 225 .RB ( readlink ()
 226 first appeared in 4.2BSD),
 227 POSIX.1-2001, POSIX.1-2008.
 228 .PP
 229 .BR readlinkat ():
 230 POSIX.1-2008.
 231 .SH NOTES
 232 In versions of glibc up to and including glibc 2.4, the return type of
 233 .BR readlink ()
 234 was declared as
 235 .IR int .
 236 Nowadays, the return type is declared as
 237 .IR ssize_t ,
 238 as (newly) required in POSIX.1-2001.
 239 .PP
 240 Using a statically sized buffer might not provide enough room for the
 241 symbolic link contents.
 242 The required size for the buffer can be obtained from the
 243 .I stat.st_size
 244 value returned by a call to
 245 .BR lstat (2)
 246 on the link.
 247 However, the number of bytes written by
 248 .BR readlink ()
 249 and
 250 .BR readlinkat ()
 251 should be checked to make sure that the size of the
 252 symbolic link did not increase between the calls.
 253 Dynamically allocating the buffer for
 254 .BR readlink ()
 255 and
 256 .BR readlinkat ()
 257 also addresses a common portability problem when using
 258 .I PATH_MAX
 259 for the buffer size,
 260 as this constant is not guaranteed to be defined per POSIX
 261 if the system does not have such limit.
 262 .SS Glibc notes
 263 On older kernels where
 264 .BR readlinkat ()
 265 is unavailable, the glibc wrapper function falls back to the use of
 266 .BR readlink ().
 267 When
 268 .I pathname
 269 is a relative pathname,
 270 glibc constructs a pathname based on the symbolic link in
 271 .IR /proc/self/fd
 272 that corresponds to the
 273 .IR dirfd
 274 argument.
 275 .SH EXAMPLES
 276 The following program allocates the buffer needed by
 277 .BR readlink ()
 278 dynamically from the information provided by
 279 .BR lstat (2),
 280 falling back to a buffer of size
 281 .BR PATH_MAX
 282 in cases where
 283 .BR lstat (2)
 284 reports a size of zero.
 285 .PP
 286 .EX
 287 #include <sys/types.h>
 288 #include <sys/stat.h>
 289 #include <limits.h>
 290 #include <stdio.h>
 291 #include <stdlib.h>
 292 #include <unistd.h>
 293
 294 int
 295 main(int argc, char *argv[])
 296 {
 297     struct stat sb;
 298     char *buf;
 299     ssize_t nbytes, bufsiz;
 300
 301     if (argc != 2) {
 302         fprintf(stderr, "Usage: %s <pathname>\en", argv[0]);
 303         exit(EXIT_FAILURE);
 304     }
 305
 306     if (lstat(argv[1], &sb) == \-1) {
 307         perror("lstat");
 308         exit(EXIT_FAILURE);
 309     }
 310
 311     /* Add one to the link size, so that we can determine whether
 312        the buffer returned by readlink() was truncated. */
 313
 314     bufsiz = sb.st_size + 1;
 315
 316     /* Some magic symlinks under (for example) /proc and /sys
 317        report \(aqst_size\(aq as zero. In that case, take PATH_MAX as
 318        a "good enough" estimate. */
 319
 320     if (sb.st_size == 0)
 321         bufsiz = PATH_MAX;
 322
 323     buf = malloc(bufsiz);
 324     if (buf == NULL) {
 325         perror("malloc");
 326         exit(EXIT_FAILURE);
 327     }
 328
 329     nbytes = readlink(argv[1], buf, bufsiz);
 330     if (nbytes == \-1) {
 331         perror("readlink");
 332         exit(EXIT_FAILURE);
 333     }
 334
 335     printf("\(aq%s\(aq points to \(aq%.*s\(aq\en", argv[1], (int) nbytes, buf);
 336
 337     /* If the return value was equal to the buffer size, then the
 338        the link target was larger than expected (perhaps because the
 339        target was changed between the call to lstat() and the call to
 340        readlink()). Warn the user that the returned target may have
 341        been truncated. */
 342
 343     if (nbytes == bufsiz)
 344         printf("(Returned buffer may have been truncated)\en");
 345
 346     free(buf);
 347     exit(EXIT_SUCCESS);
 348 }
 349 .EE
 350 .SH SEE ALSO
 351 .BR readlink (1),
 352 .BR lstat (2),
 353 .BR stat (2),
 354 .BR symlink (2),
 355 .BR realpath (3),
 356 .BR path_resolution (7),
 357 .BR symlink (7)