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 .\" SPDX-License-Identifier: BSD-4-Clause-UC
   7 .\"
   8 .\"     @(#)readlink.2  6.8 (Berkeley) 3/10/91
   9 .\"
  10 .\" Modified Sat Jul 24 00:10:21 1993 by Rik Faith (faith@cs.unc.edu)
  11 .\" Modified Tue Jul  9 23:55:17 1996 by aeb
  12 .\" Modified Fri Jan 24 00:26:00 1997 by aeb
  13 .\" 2011-09-20, Guillem Jover <guillem@hadrons.org>:
  14 .\"     Added text on dynamically allocating buffer + example program
  15 .\"
  16 .TH READLINK 2 2021-08-27 "Linux" "Linux Programmer's Manual"
  17 .SH NAME
  18 readlink, readlinkat \- read value of a symbolic link
  19 .SH LIBRARY
  20 Standard C library
  21 .RI ( libc ", " \-lc )
  22 .SH SYNOPSIS
  23 .nf
  24 .B #include <unistd.h>
  25 .PP
  26 .BI "ssize_t readlink(const char *restrict " pathname ", char *restrict " buf ,
  27 .BI "                 size_t " bufsiz );
  28 .PP
  29 .BR "#include <fcntl.h>            " "/* Definition of " AT_* " constants */"
  30 .B #include <unistd.h>
  31 .PP
  32 .BI "ssize_t readlinkat(int " dirfd ", const char *restrict " pathname ,
  33 .BI "                 char *restrict " buf ", size_t " bufsiz );
  34 .PP
  35 .fi
  36 .RS -4
  37 Feature Test Macro Requirements for glibc (see
  38 .BR feature_test_macros (7)):
  39 .RE
  40 .PP
  41 .BR readlink ():
  42 .nf
  43     _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L
  44 .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
  45         || /* Glibc <= 2.19: */ _BSD_SOURCE
  46 .fi
  47 .PP
  48 .BR readlinkat ():
  49 .nf
  50     Since glibc 2.10:
  51         _POSIX_C_SOURCE >= 200809L
  52     Before glibc 2.10:
  53         _ATFILE_SOURCE
  54 .fi
  55 .SH DESCRIPTION
  56 .BR readlink ()
  57 places the contents of the symbolic link
  58 .I pathname
  59 in the buffer
  60 .IR buf ,
  61 which has size
  62 .IR bufsiz .
  63 .BR readlink ()
  64 does not append a terminating null byte to
  65 .IR buf .
  66 It will (silently) truncate the contents (to a length of
  67 .I bufsiz
  68 characters), in case the buffer is too small to hold all of the contents.
  69 .SS readlinkat()
  70 The
  71 .BR readlinkat ()
  72 system call operates in exactly the same way as
  73 .BR readlink (),
  74 except for the differences described here.
  75 .PP
  76 If the pathname given in
  77 .I pathname
  78 is relative, then it is interpreted relative to the directory
  79 referred to by the file descriptor
  80 .I dirfd
  81 (rather than relative to the current working directory of
  82 the calling process, as is done by
  83 .BR readlink ()
  84 for a relative pathname).
  85 .PP
  86 If
  87 .I pathname
  88 is relative and
  89 .I dirfd
  90 is the special value
  91 .BR AT_FDCWD ,
  92 then
  93 .I pathname
  94 is interpreted relative to the current working
  95 directory of the calling process (like
  96 .BR readlink ()).
  97 .PP
  98 If
  99 .I pathname
 100 is absolute, then
 101 .I dirfd
 102 is ignored.
 103 .PP
 104 Since Linux 2.6.39,
 105 .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
 106 .I pathname
 107 can be an empty string,
 108 in which case the call operates on the symbolic link referred to by
 109 .I dirfd
 110 (which should have been obtained using
 111 .BR open (2)
 112 with the
 113 .B O_PATH
 114 and
 115 .B O_NOFOLLOW
 116 flags).
 117 .PP
 118 See
 119 .BR openat (2)
 120 for an explanation of the need for
 121 .BR readlinkat ().
 122 .SH RETURN VALUE
 123 On success, these calls return the number of bytes placed in
 124 .IR buf .
 125 (If the returned value equals
 126 .IR bufsiz ,
 127 then truncation may have occurred.)
 128 On error, \-1 is returned and
 129 .I errno
 130 is set to indicate the error.
 131 .SH ERRORS
 132 .TP
 133 .B EACCES
 134 Search permission is denied for a component of the path prefix.
 135 (See also
 136 .BR path_resolution (7).)
 137 .TP
 138 .B EBADF
 139 .RB ( readlinkat ())
 140 .I pathname
 141 is relative but
 142 .I dirfd
 143 is neither
 144 .B AT_FDCWD
 145 nor a valid file descriptor.
 146 .TP
 147 .B EFAULT
 148 .I buf
 149 extends outside the process's allocated address space.
 150 .TP
 151 .B EINVAL
 152 .I bufsiz
 153 is not positive.
 154 .\" At the glibc level, bufsiz is unsigned, so this error can only occur
 155 .\" if bufsiz==0.  However, the in the kernel syscall, bufsiz is signed,
 156 .\" and this error can also occur if bufsiz < 0.
 157 .\" See: http://thread.gmane.org/gmane.linux.man/380
 158 .\" Subject: [patch 0/3] [RFC] kernel/glibc mismatch of "readlink" syscall?
 159 .TP
 160 .B EINVAL
 161 The named file (i.e., the final filename component of
 162 .IR pathname )
 163 is not a symbolic link.
 164 .TP
 165 .B EIO
 166 An I/O error occurred while reading from the filesystem.
 167 .TP
 168 .B ELOOP
 169 Too many symbolic links were encountered in translating the pathname.
 170 .TP
 171 .B ENAMETOOLONG
 172 A pathname, or a component of a pathname, was too long.
 173 .TP
 174 .B ENOENT
 175 The named file does not exist.
 176 .TP
 177 .B ENOMEM
 178 Insufficient kernel memory was available.
 179 .TP
 180 .B ENOTDIR
 181 A component of the path prefix is not a directory.
 182 .TP
 183 .B ENOTDIR
 184 .RB ( readlinkat ())
 185 .I pathname
 186 is relative and
 187 .I dirfd
 188 is a file descriptor referring to a file other than a directory.
 189 .SH VERSIONS
 190 .BR readlinkat ()
 191 was added to Linux in kernel 2.6.16;
 192 library support was added to glibc in version 2.4.
 193 .SH STANDARDS
 194 .BR readlink ():
 195 4.4BSD
 196 .RB ( readlink ()
 197 first appeared in 4.2BSD),
 198 POSIX.1-2001, POSIX.1-2008.
 199 .PP
 200 .BR readlinkat ():
 201 POSIX.1-2008.
 202 .SH NOTES
 203 In versions of glibc up to and including glibc 2.4, the return type of
 204 .BR readlink ()
 205 was declared as
 206 .IR int .
 207 Nowadays, the return type is declared as
 208 .IR ssize_t ,
 209 as (newly) required in POSIX.1-2001.
 210 .PP
 211 Using a statically sized buffer might not provide enough room for the
 212 symbolic link contents.
 213 The required size for the buffer can be obtained from the
 214 .I stat.st_size
 215 value returned by a call to
 216 .BR lstat (2)
 217 on the link.
 218 However, the number of bytes written by
 219 .BR readlink ()
 220 and
 221 .BR readlinkat ()
 222 should be checked to make sure that the size of the
 223 symbolic link did not increase between the calls.
 224 Dynamically allocating the buffer for
 225 .BR readlink ()
 226 and
 227 .BR readlinkat ()
 228 also addresses a common portability problem when using
 229 .B PATH_MAX
 230 for the buffer size,
 231 as this constant is not guaranteed to be defined per POSIX
 232 if the system does not have such limit.
 233 .SS Glibc notes
 234 On older kernels where
 235 .BR readlinkat ()
 236 is unavailable, the glibc wrapper function falls back to the use of
 237 .BR readlink ().
 238 When
 239 .I pathname
 240 is a relative pathname,
 241 glibc constructs a pathname based on the symbolic link in
 242 .I /proc/self/fd
 243 that corresponds to the
 244 .I dirfd
 245 argument.
 246 .SH EXAMPLES
 247 The following program allocates the buffer needed by
 248 .BR readlink ()
 249 dynamically from the information provided by
 250 .BR lstat (2),
 251 falling back to a buffer of size
 252 .B PATH_MAX
 253 in cases where
 254 .BR lstat (2)
 255 reports a size of zero.
 256 .PP
 257 .\" SRC BEGIN (readlink.c)
 258 .EX
 259 #include <limits.h>
 260 #include <stdio.h>
 261 #include <stdlib.h>
 262 #include <sys/stat.h>
 263 #include <unistd.h>
 264
 265 int
 266 main(int argc, char *argv[])
 267 {
 268     struct stat sb;
 269     char *buf;
 270     ssize_t nbytes, bufsiz;
 271
 272     if (argc != 2) {
 273         fprintf(stderr, "Usage: %s <pathname>\en", argv[0]);
 274         exit(EXIT_FAILURE);
 275     }
 276
 277     if (lstat(argv[1], &sb) == \-1) {
 278         perror("lstat");
 279         exit(EXIT_FAILURE);
 280     }
 281
 282     /* Add one to the link size, so that we can determine whether
 283        the buffer returned by readlink() was truncated. */
 284
 285     bufsiz = sb.st_size + 1;
 286
 287     /* Some magic symlinks under (for example) /proc and /sys
 288        report \(aqst_size\(aq as zero. In that case, take PATH_MAX as
 289        a "good enough" estimate. */
 290
 291     if (sb.st_size == 0)
 292         bufsiz = PATH_MAX;
 293
 294     buf = malloc(bufsiz);
 295     if (buf == NULL) {
 296         perror("malloc");
 297         exit(EXIT_FAILURE);
 298     }
 299
 300     nbytes = readlink(argv[1], buf, bufsiz);
 301     if (nbytes == \-1) {
 302         perror("readlink");
 303         exit(EXIT_FAILURE);
 304     }
 305
 306     /* Print only \(aqnbytes\(aq of \(aqbuf\(aq, as it doesn't contain a terminating
 307        null byte (\(aq\e0\(aq). */
 308     printf("\(aq%s\(aq points to \(aq%.*s\(aq\en", argv[1], (int) nbytes, buf);
 309
 310     /* If the return value was equal to the buffer size, then the
 311        the link target was larger than expected (perhaps because the
 312        target was changed between the call to lstat() and the call to
 313        readlink()). Warn the user that the returned target may have
 314        been truncated. */
 315
 316     if (nbytes == bufsiz)
 317         printf("(Returned buffer may have been truncated)\en");
 318
 319     free(buf);
 320     exit(EXIT_SUCCESS);
 321 }
 322 .EE
 323 .\" SRC END
 324 .SH SEE ALSO
 325 .BR readlink (1),
 326 .BR lstat (2),
 327 .BR stat (2),
 328 .BR symlink (2),
 329 .BR realpath (3),
 330 .BR path_resolution (7),
 331 .BR symlink (7)