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