1READLINK(3P)               POSIX Programmer's Manual              READLINK(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       readlink - read the contents of a symbolic link
13

SYNOPSIS

15       #include <unistd.h>
16
17       ssize_t readlink(const char *restrict path, char *restrict buf,
18              size_t bufsize);
19
20

DESCRIPTION

22       The readlink() function shall place the contents of the  symbolic  link
23       referred  to  by  path in the buffer buf which has size bufsize. If the
24       number of bytes in the symbolic link is less than bufsize, the contents
25       of  the  remainder  of  buf are unspecified. If the buf argument is not
26       large enough to contain the link content, the first bufsize bytes shall
27       be placed in buf.
28
29       If  the  value  of  bufsize  is greater than {SSIZE_MAX}, the result is
30       implementation-defined.
31

RETURN VALUE

33       Upon successful completion, readlink() shall return the count of  bytes
34       placed  in  the buffer. Otherwise, it shall return a value of -1, leave
35       the buffer unchanged, and set errno to indicate the error.
36

ERRORS

38       The readlink() function shall fail if:
39
40       EACCES Search permission is denied for a component of the  path  prefix
41              of path.
42
43       EINVAL The path argument names a file that is not a symbolic link.
44
45       EIO    An I/O error occurred while reading from the file system.
46
47       ELOOP  A loop exists in symbolic links encountered during resolution of
48              the path argument.
49
50       ENAMETOOLONG
51              The length of the path argument exceeds {PATH_MAX} or a pathname
52              component is longer than {NAME_MAX}.
53
54       ENOENT A component of path does not name an existing file or path is an
55              empty string.
56
57       ENOTDIR
58              A component of the path prefix is not a directory.
59
60
61       The readlink() function may fail if:
62
63       EACCES Read permission is denied for the directory.
64
65       ELOOP  More than {SYMLOOP_MAX} symbolic links were  encountered  during
66              resolution of the path argument.
67
68       ENAMETOOLONG
69              As a result of encountering a symbolic link in resolution of the
70              path argument, the length of  the  substituted  pathname  string
71              exceeded {PATH_MAX}.
72
73
74       The following sections are informative.
75

EXAMPLES

77   Reading the Name of a Symbolic Link
78       The  following  example  shows  how to read the name of a symbolic link
79       named /modules/pass1.
80
81
82              #include <unistd.h>
83
84
85              char buf[1024];
86              ssize_t len;
87              ...
88              if ((len = readlink("/modules/pass1", buf, sizeof(buf)-1)) != -1)
89                  buf[len] = '\0';
90

APPLICATION USAGE

92       Conforming applications should not assume that the returned contents of
93       the symbolic link are null-terminated.
94

RATIONALE

96       Since  IEEE Std 1003.1-2001  does  not  require any association of file
97       times with symbolic links, there is no requirement that file  times  be
98       updated  by  readlink(). The type associated with bufsiz is a size_t in
99       order to be consistent with both the ISO C standard and the  definition
100       of  read().   The behavior specified for readlink() when bufsiz is zero
101       represents historical practice. For this case, the standard  developers
102       considered  a change whereby readlink() would return the number of non-
103       null bytes contained in the symbolic link with the buffer buf remaining
104       unchanged;  however,  since the stat structure member st_size value can
105       be used to determine the size of buffer necessary to contain  the  con‐
106       tents of the symbolic link as returned by readlink(), this proposal was
107       rejected, and the historical practice retained.
108

FUTURE DIRECTIONS

110       None.
111

SEE ALSO

113       lstat(),  stat(),   symlink(),   the   Base   Definitions   volume   of
114       IEEE Std 1003.1-2001, <unistd.h>
115

117       Portions  of  this text are reprinted and reproduced in electronic form
118       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
119       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
120       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
121       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
122       event of any discrepancy between this version and the original IEEE and
123       The  Open Group Standard, the original IEEE and The Open Group Standard
124       is the referee document. The original Standard can be  obtained  online
125       at http://www.opengroup.org/unix/online.html .
126
127
128
129IEEE/The Open Group                  2003                         READLINK(3P)
Impressum