original/man2/readlink.2

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