1READLINK(P) POSIX Programmer's Manual READLINK(P)
2
6 readlink - read the contents of a symbolic link
7
9 #include <unistd.h>
10 ssize_t readlink(const char *restrict path, char *restrict buf,
12 size_t bufsize);
13
16 The readlink() function shall place the contents of the symbolic link
17 referred to by path in the buffer buf which has size bufsize. If the
18 number of bytes in the symbolic link is less than bufsize, the contents
19 of the remainder of buf are unspecified. If the buf argument is not
20 large enough to contain the link content, the first bufsize bytes shall
21 be placed in buf.
22 If the value of bufsize is greater than {SSIZE_MAX}, the result is
24 implementation-defined.
25
27 Upon successful completion, readlink() shall return the count of bytes
28 placed in the buffer. Otherwise, it shall return a value of -1, leave
29 the buffer unchanged, and set errno to indicate the error.
30
32 The readlink() function shall fail if:
33 EACCES Search permission is denied for a component of the path prefix
35 of path.
36 EINVAL The path argument names a file that is not a symbolic link.
38 EIO An I/O error occurred while reading from the file system.
40 ELOOP A loop exists in symbolic links encountered during resolution of
42 the path argument.
43 ENAMETOOLONG
45 The length of the path argument exceeds {PATH_MAX} or a pathname
46 component is longer than {NAME_MAX}.
47 ENOENT A component of path does not name an existing file or path is an
49 empty string.
50 ENOTDIR
52 A component of the path prefix is not a directory.
53 The readlink() function may fail if:
56 EACCES Read permission is denied for the directory.
58 ELOOP More than {SYMLOOP_MAX} symbolic links were encountered during
60 resolution of the path argument.
61 ENAMETOOLONG
63 As a result of encountering a symbolic link in resolution of the
64 path argument, the length of the substituted pathname string
65 exceeded {PATH_MAX}.
66 The following sections are informative.
69
71 Reading the Name of a Symbolic Link
72 The following example shows how to read the name of a symbolic link
73 named /modules/pass1.
74 #include <unistd.h>
77 char buf[1024];
80 ssizet_t len;
81 ...
82 if ((len = readlink("/modules/pass1", buf, sizeof(buf)-1)) != -1)
83 buf[len] = '\0';
84
86 Conforming applications should not assume that the returned contents of
87 the symbolic link are null-terminated.
88
90 Since IEEE Std 1003.1-2001 does not require any association of file
91 times with symbolic links, there is no requirement that file times be
92 updated by readlink(). The type associated with bufsiz is a size_t in
93 order to be consistent with both the ISO C standard and the definition
94 of read(). The behavior specified for readlink() when bufsiz is zero
95 represents historical practice. For this case, the standard developers
96 considered a change whereby readlink() would return the number of non-
97 null bytes contained in the symbolic link with the buffer buf remaining
98 unchanged; however, since the stat structure member st_size value can
99 be used to determine the size of buffer necessary to contain the con‐
100 tents of the symbolic link as returned by readlink(), this proposal was
101 rejected, and the historical practice retained.
102
104 None.
105
107 lstat() , stat() , symlink() , the Base Definitions volume of
108 IEEE Std 1003.1-2001, <unistd.h>
109
111 Portions of this text are reprinted and reproduced in electronic form
112 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
113 -- Portable Operating System Interface (POSIX), The Open Group Base
114 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
115 Electrical and Electronics Engineers, Inc and The Open Group. In the
116 event of any discrepancy between this version and the original IEEE and
117 The Open Group Standard, the original IEEE and The Open Group Standard
118 is the referee document. The original Standard can be obtained online
119 at http://www.opengroup.org/unix/online.html .
120IEEE/The Open Group 2003 READLINK(P)