1READLINK(3P) POSIX Programmer's Manual READLINK(3P)
2
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
12 readlink, readlinkat — read the contents of a symbolic link
13
15 #include <unistd.h>
16 ssize_t readlink(const char *restrict path, char *restrict buf,
18 size_t bufsize);
19 #include <fcntl.h>
21 ssize_t readlinkat(int fd, const char *restrict path,
23 char *restrict buf, size_t bufsize);
24
26 The readlink() function shall place the contents of the symbolic link
27 referred to by path in the buffer buf which has size bufsize. If the
28 number of bytes in the symbolic link is less than bufsize, the contents
29 of the remainder of buf are unspecified. If the buf argument is not
30 large enough to contain the link content, the first bufsize bytes shall
31 be placed in buf.
32 If the value of bufsize is greater than {SSIZE_MAX}, the result is
34 implementation-defined.
35 Upon successful completion, readlink() shall mark for update the last
37 data access timestamp of the symbolic link.
38 The readlinkat() function shall be equivalent to the readlink() func‐
40 tion except in the case where path specifies a relative path. In this
41 case the symbolic link whose content is read is relative to the direc‐
42 tory associated with the file descriptor fd instead of the current
43 working directory. If the access mode of the open file description
44 associated with the file descriptor is not O_SEARCH, the function shall
45 check whether directory searches are permitted using the current per‐
46 missions of the directory underlying the file descriptor. If the access
47 mode is O_SEARCH, the function shall not perform the check.
48 If readlinkat() is passed the special value AT_FDCWD in the fd parame‐
50 ter, the current working directory shall be used and the behavior shall
51 be identical to a call to readlink().
52
54 Upon successful completion, these functions shall return the count of
55 bytes placed in the buffer. Otherwise, these functions shall return a
56 value of -1, leave the buffer unchanged, and set errno to indicate the
57 error.
58
60 These functions shall fail if:
61 EACCES Search permission is denied for a component of the path prefix
63 of path.
64 EINVAL The path argument names a file that is not a symbolic link.
66 EIO An I/O error occurred while reading from the file system.
68 ELOOP A loop exists in symbolic links encountered during resolution of
70 the path argument.
71 ENAMETOOLONG
73 The length of a component of a pathname is longer than
74 {NAME_MAX}.
75 ENOENT A component of path does not name an existing file or path is an
77 empty string.
78 ENOTDIR
80 A component of the path prefix names an existing file that is
81 neither a directory nor a symbolic link to a directory, or the
82 path argument contains at least one non-<slash> character and
83 ends with one or more trailing <slash> characters and the last
84 pathname component names an existing file that is neither a
85 directory nor a symbolic link to a directory.
86 The readlinkat() function shall fail if:
88 EACCES The access mode of the open file description associated with fd
90 is not O_SEARCH and the permissions of the directory underlying
91 fd do not permit directory searches.
92 EBADF The path argument does not specify an absolute path and the fd
94 argument is neither AT_FDCWD nor a valid file descriptor open
95 for reading or searching.
96 ENOTDIR
98 The path argument is not an absolute path and fd is a file
99 descriptor associated with a non-directory file.
100 These functions may fail if:
102 ELOOP More than {SYMLOOP_MAX} symbolic links were encountered during
104 resolution of the path argument.
105 ENAMETOOLONG
107 The length of a pathname exceeds {PATH_MAX}, or pathname resolu‐
108 tion of a symbolic link produced an intermediate result with a
109 length that exceeds {PATH_MAX}.
110 The following sections are informative.
112
114 Reading the Name of a Symbolic Link
115 The following example shows how to read the name of a symbolic link
116 named /modules/pass1.
117 #include <unistd.h>
120 char buf[1024];
122 ssize_t len;
123 ...
124 if ((len = readlink("/modules/pass1", buf, sizeof(buf)-1)) != -1)
125 buf[len] = '\0';
126
128 Conforming applications should not assume that the returned contents of
129 the symbolic link are null-terminated.
130
132 The type associated with bufsiz is a size_t in order to be consistent
133 with both the ISO C standard and the definition of read(). The behav‐
134 ior specified for readlink() when bufsiz is zero represents historical
135 practice. For this case, the standard developers considered a change
136 whereby readlink() would return the number of non-null bytes contained
137 in the symbolic link with the buffer buf remaining unchanged; however,
138 since the stat structure member st_size value can be used to determine
139 the size of buffer necessary to contain the contents of the symbolic
140 link as returned by readlink(), this proposal was rejected, and the
141 historical practice retained.
142 The purpose of the readlinkat() function is to read the content of sym‐
144 bolic links in directories other than the current working directory
145 without exposure to race conditions. Any part of the path of a file
146 could be changed in parallel to a call to readlink(), resulting in
147 unspecified behavior. By opening a file descriptor for the target
148 directory and using the readlinkat() function it can be guaranteed that
149 the symbolic link read is located relative to the desired directory.
150
152 None.
153
155 fstatat(), symlink()
156 The Base Definitions volume of POSIX.1‐2017, <fcntl.h>, <unistd.h>
158
160 Portions of this text are reprinted and reproduced in electronic form
161 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
162 table Operating System Interface (POSIX), The Open Group Base Specifi‐
163 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
164 Electrical and Electronics Engineers, Inc and The Open Group. In the
165 event of any discrepancy between this version and the original IEEE and
166 The Open Group Standard, the original IEEE and The Open Group Standard
167 is the referee document. The original Standard can be obtained online
168 at http://www.opengroup.org/unix/online.html .
169 Any typographical or formatting errors that appear in this page are
171 most likely to have been introduced during the conversion of the source
172 files to man page format. To report such errors, see https://www.ker‐
173 nel.org/doc/man-pages/reporting_bugs.html .
174IEEE/The Open Group 2017 READLINK(3P)