1.\" Copyright (c) 1983, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)readlink.2 8.1 (Berkeley) 6/4/93 29.\" $FreeBSD: src/lib/libc/sys/readlink.2,v 1.17 2008/04/16 13:03:12 kib Exp $ 30.\" 31.Dd August 6, 2010 32.Dt READLINK 2 33.Os 34.Sh NAME 35.Nm readlink , 36.Nm readlinkat 37.Nd read value of a symbolic link 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 41.In unistd.h 42.Ft ssize_t 43.Fn readlink "const char * restrict path" "char * restrict buf" "size_t bufsiz" 44.Ft ssize_t 45.Fn readlinkat "int fd" "const char * restrict path" "char * restrict buf" "size_t bufsize" 46.Sh DESCRIPTION 47The 48.Fn readlink 49system call 50places the contents of the symbolic link 51.Fa path 52in the buffer 53.Fa buf , 54which has size 55.Fa bufsiz . 56The 57.Fn readlink 58system call does not append a 59.Dv NUL 60character to 61.Fa buf . 62.Pp 63The 64.Fn readlinkat 65system call is equivalent to 66.Fn readlink 67except in the case where 68.Fa path 69specifies a relative path. 70In this case the symbolic link whose content is read relative to the 71directory associated with the file descriptor 72.Fa fd 73instead of the current working directory. 74If 75.Fn readlinkat 76is passed the special value 77.Dv AT_FDCWD 78in the 79.Fa fd 80parameter, the current working directory is used and the behavior is 81identical to a call to 82.Fn readlink . 83.Sh RETURN VALUES 84The calls return the count of characters placed in the buffer 85if it succeeds, or a \-1 if an error occurs, placing the error 86code in the global variable 87.Va errno . 88.Sh ERRORS 89The 90.Fn readlink 91system call 92will fail if: 93.Bl -tag -width Er 94.It Bq Er ENOTDIR 95A component of the path prefix is not a directory. 96.It Bq Er ENAMETOOLONG 97A component of a pathname exceeded 255 characters, 98or an entire path name exceeded 1023 characters. 99.It Bq Er ENOENT 100The named file does not exist. 101.It Bq Er EACCES 102Search permission is denied for a component of the path prefix. 103.It Bq Er ELOOP 104Too many symbolic links were encountered in translating the pathname. 105.It Bq Er EINVAL 106The named file is not a symbolic link. 107.It Bq Er EIO 108An I/O error occurred while reading from the file system. 109.It Bq Er EFAULT 110The 111.Fa buf 112argument 113extends outside the process's allocated address space. 114.El 115.Pp 116In addition to the errors returned by the 117.Fn readlink , 118the 119.Fn readlinkat 120may fail if: 121.Bl -tag -width Er 122.It Bq Er EBADF 123The 124.Fa path 125argument does not specify an absolute path and the 126.Fa fd 127argument is neither 128.Dv AT_FDCWD 129nor a valid file descriptor open for searching. 130.It Bq Er ENOTDIR 131The 132.Fa path 133argument is not an absolute path and 134.Fa fd 135is neither 136.Dv AT_FDCWD 137nor a file descriptor associated with a directory. 138.El 139.Sh SEE ALSO 140.Xr lstat 2 , 141.Xr stat 2 , 142.Xr symlink 2 , 143.Xr symlink 7 144.Sh STANDARDS 145The 146.Fn readlinkat 147system call follows The Open Group Extended API Set 2 specification. 148.Sh HISTORY 149The 150.Fn readlink 151system call appeared in 152.Bx 4.2 . 153The 154.Fn readlinkat 155system call appeared in 156.Dx 2.7 . 157