manual/LDP_man-pages/original/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 .\" All rights reserved.
   4 .\"
   5 .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\" %%%LICENSE_END
  34 .\"
  35 .\"     @(#)readlink.2  6.8 (Berkeley) 3/10/91
  36 .\"
  37 .\" Modified Sat Jul 24 00:10:21 1993 by Rik Faith (faith@cs.unc.edu)
  38 .\" Modified Tue Jul  9 23:55:17 1996 by aeb
  39 .\" Modified Fri Jan 24 00:26:00 1997 by aeb
  40 .\" 2011-09-20, Guillem Jover <guillem@hadrons.org>:
  41 .\"     Added text on dynamically allocating buffer + example program
  42 .\"
  43 .TH READLINK 2 2013-07-18 "Linux" "Linux Programmer's Manual"
  44 .SH NAME
  45 readlink \- read value of a symbolic link
  46 .SH SYNOPSIS
  47 .B #include <unistd.h>
  48 .sp
  49 .BI "ssize_t readlink(const char *" path ", char *" buf ", size_t " bufsiz );
  50 .sp
  51 .in -4n
  52 Feature Test Macro Requirements for glibc (see
  53 .BR feature_test_macros (7)):
  54 .in
  55 .sp
  56 .ad l
  57 .BR readlink ():
  58 .RS 4
  59 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 ||
  60 _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED || _POSIX_C_SOURCE\ >=\ 200112L
  61 .RE
  62 .ad b
  63 .SH DESCRIPTION
  64 .BR readlink ()
  65 places the contents of the symbolic link
  66 .I path
  67 in the buffer
  68 .IR buf ,
  69 which has size
  70 .IR bufsiz .
  71 .BR readlink ()
  72 does not append a null byte to
  73 .IR buf .
  74 It will truncate the contents (to a length of
  75 .I bufsiz
  76 characters), in case the buffer is too small to hold all of the contents.
  77 .SH RETURN VALUE
  78 On success,
  79 .BR readlink ()
  80 returns the number of bytes placed in
  81 .IR buf .
  82 On error, \-1 is returned and
  83 .I errno
  84 is set to indicate the error.
  85 .SH ERRORS
  86 .TP
  87 .B EACCES
  88 Search permission is denied for a component of the path prefix.
  89 (See also
  90 .BR path_resolution (7).)
  91 .TP
  92 .B EFAULT
  93 .I buf
  94 extends outside the process's allocated address space.
  95 .TP
  96 .B EINVAL
  97 .I bufsiz
  98 is not positive.
  99 .\" At the glibc level, bufsiz is unsigned, so this error can only occur
 100 .\" if bufsiz==0.  However, the in the kernel syscall, bufsiz is signed,
 101 .\" and this error can also occur if bufsiz < 0.
 102 .\" See: http://thread.gmane.org/gmane.linux.man/380
 103 .\" Subject: [patch 0/3] [RFC] kernel/glibc mismatch of "readlink" syscall?
 104 .TP
 105 .B EINVAL
 106 The named file is not a symbolic link.
 107 .TP
 108 .B EIO
 109 An I/O error occurred while reading from the file system.
 110 .TP
 111 .B ELOOP
 112 Too many symbolic links were encountered in translating the pathname.
 113 .TP
 114 .B ENAMETOOLONG
 115 A pathname, or a component of a pathname, was too long.
 116 .TP
 117 .B ENOENT
 118 The named file does not exist.
 119 .TP
 120 .B ENOMEM
 121 Insufficient kernel memory was available.
 122 .TP
 123 .B ENOTDIR
 124 A component of the path prefix is not a directory.
 125 .SH CONFORMING TO
 126 4.4BSD
 127 .RB ( readlink ()
 128 first appeared in 4.2BSD),
 129 POSIX.1-2001.
 130 .SH NOTES
 131 In versions of glibc up to and including glibc 2.4, the return type of
 132 .BR readlink ()
 133 was declared as
 134 .IR int .
 135 Nowadays, the return type is declared as
 136 .IR ssize_t ,
 137 as (newly) required in POSIX.1-2001.
 138
 139 Using a statically sized buffer might not provide enough room for the
 140 symbolic link contents.
 141 The required size for the buffer can be obtained from the
 142 .I stat.st_size
 143 value returned by a call to
 144 .BR lstat (2)
 145 on the link.
 146 However, the number of bytes written by
 147 .BR readlink ()
 148 should be checked to make sure that the size of the
 149 symbolic link did not increase between the calls.
 150 Dynamically allocating the buffer for
 151 .BR readlink ()
 152 also addresses a common portability problem when using
 153 .I PATH_MAX
 154 for the buffer size,
 155 as this constant is not guaranteed to be defined per POSIX
 156 if the system does not have such limit.
 157 .SH EXAMPLE
 158 The following program allocates the buffer needed by
 159 .BR readlink ()
 160 dynamically from the information provided by
 161 .BR lstat (),
 162 making sure there's no race condition between the calls.
 163 .nf
 164
 165 #include <sys/types.h>
 166 #include <sys/stat.h>
 167 #include <stdio.h>
 168 #include <stdlib.h>
 169 #include <unistd.h>
 170
 171 int
 172 main(int argc, char *argv[])
 173 {
 174     struct stat sb;
 175     char *linkname;
 176     ssize_t r;
 177
 178     if (argc != 2) {
 179         fprintf(stderr, "Usage: %s <pathname>\\n", argv[0]);
 180         exit(EXIT_FAILURE);
 181     }
 182
 183     if (lstat(argv[1], &sb) == \-1) {
 184         perror("lstat");
 185         exit(EXIT_FAILURE);
 186     }
 187
 188     linkname = malloc(sb.st_size + 1);
 189     if (linkname == NULL) {
 190         fprintf(stderr, "insufficient memory\\n");
 191         exit(EXIT_FAILURE);
 192     }
 193
 194     r = readlink(argv[1], linkname, sb.st_size + 1);
 195
 196     if (r == \-1) {
 197         perror("lstat");
 198         exit(EXIT_FAILURE);
 199     }
 200
 201     if (r > sb.st_size) {
 202         fprintf(stderr, "symlink increased in size "
 203                         "between lstat() and readlink()\\n");
 204         exit(EXIT_FAILURE);
 205     }
 206
 207     linkname[r] = \(aq\\0\(aq;
 208
 209     printf("\(aq%s\(aq points to \(aq%s\(aq\\n", argv[1], linkname);
 210
 211     exit(EXIT_SUCCESS);
 212 }
 213 .fi
 214 .SH SEE ALSO
 215 .BR readlink (1),
 216 .BR lstat (2),
 217 .BR readlinkat (2),
 218 .BR stat (2),
 219 .BR symlink (2),
 220 .BR path_resolution (7),
 221 .BR symlink (7)