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