xref: /freebsd/lib/libsys/readlink.2 (revision aebac84982567b9f026174f545f27902ae371027)
18269e767SBrooks Davis.\" Copyright (c) 1983, 1991, 1993
28269e767SBrooks Davis.\"	The Regents of the University of California.  All rights reserved.
38269e767SBrooks Davis.\"
48269e767SBrooks Davis.\" Redistribution and use in source and binary forms, with or without
58269e767SBrooks Davis.\" modification, are permitted provided that the following conditions
68269e767SBrooks Davis.\" are met:
78269e767SBrooks Davis.\" 1. Redistributions of source code must retain the above copyright
88269e767SBrooks Davis.\"    notice, this list of conditions and the following disclaimer.
98269e767SBrooks Davis.\" 2. Redistributions in binary form must reproduce the above copyright
108269e767SBrooks Davis.\"    notice, this list of conditions and the following disclaimer in the
118269e767SBrooks Davis.\"    documentation and/or other materials provided with the distribution.
128269e767SBrooks Davis.\" 3. Neither the name of the University nor the names of its contributors
138269e767SBrooks Davis.\"    may be used to endorse or promote products derived from this software
148269e767SBrooks Davis.\"    without specific prior written permission.
158269e767SBrooks Davis.\"
168269e767SBrooks Davis.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
178269e767SBrooks Davis.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
188269e767SBrooks Davis.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
198269e767SBrooks Davis.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
208269e767SBrooks Davis.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
218269e767SBrooks Davis.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
228269e767SBrooks Davis.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
238269e767SBrooks Davis.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
248269e767SBrooks Davis.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
258269e767SBrooks Davis.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
268269e767SBrooks Davis.\" SUCH DAMAGE.
278269e767SBrooks Davis.\"
288269e767SBrooks Davis.Dd March 30, 2020
298269e767SBrooks Davis.Dt READLINK 2
308269e767SBrooks Davis.Os
318269e767SBrooks Davis.Sh NAME
328269e767SBrooks Davis.Nm readlink ,
338269e767SBrooks Davis.Nm readlinkat
348269e767SBrooks Davis.Nd read value of a symbolic link
358269e767SBrooks Davis.Sh LIBRARY
368269e767SBrooks Davis.Lb libc
378269e767SBrooks Davis.Sh SYNOPSIS
388269e767SBrooks Davis.In unistd.h
398269e767SBrooks Davis.Ft ssize_t
408269e767SBrooks Davis.Fn readlink "const char *restrict path" "char *restrict buf" "size_t bufsiz"
418269e767SBrooks Davis.Ft ssize_t
428269e767SBrooks Davis.Fo readlinkat
438269e767SBrooks Davis.Fa "int fd" "const char *restrict path" "char *restrict buf" "size_t bufsize"
448269e767SBrooks Davis.Fc
458269e767SBrooks Davis.Sh DESCRIPTION
468269e767SBrooks DavisThe
478269e767SBrooks Davis.Fn readlink
488269e767SBrooks Davissystem call
498269e767SBrooks Davisplaces the contents of the symbolic link
508269e767SBrooks Davis.Fa path
518269e767SBrooks Davisin the buffer
528269e767SBrooks Davis.Fa buf ,
538269e767SBrooks Daviswhich has size
548269e767SBrooks Davis.Fa bufsiz .
558269e767SBrooks DavisThe
568269e767SBrooks Davis.Fn readlink
578269e767SBrooks Davissystem call does not append a
588269e767SBrooks Davis.Dv NUL
598269e767SBrooks Davischaracter to
608269e767SBrooks Davis.Fa buf .
618269e767SBrooks Davis.Pp
628269e767SBrooks DavisThe
638269e767SBrooks Davis.Fn readlinkat
648269e767SBrooks Davissystem call is equivalent to
658269e767SBrooks Davis.Fn readlink
668269e767SBrooks Davisexcept in the case where
678269e767SBrooks Davis.Fa path
688269e767SBrooks Davisspecifies a relative path.
698269e767SBrooks DavisIn this case the symbolic link whose content is read relative to the
708269e767SBrooks Davisdirectory associated with the file descriptor
718269e767SBrooks Davis.Fa fd
728269e767SBrooks Davisinstead of the current working directory.
738269e767SBrooks DavisIf
748269e767SBrooks Davis.Fn readlinkat
758269e767SBrooks Davisis passed the special value
768269e767SBrooks Davis.Dv AT_FDCWD
778269e767SBrooks Davisin the
788269e767SBrooks Davis.Fa fd
798269e767SBrooks Davisparameter, the current working directory is used and the behavior is
808269e767SBrooks Davisidentical to a call to
818269e767SBrooks Davis.Fn readlink .
828269e767SBrooks Davis.Sh RETURN VALUES
838269e767SBrooks DavisThe call returns the count of characters placed in the buffer
848269e767SBrooks Davisif it succeeds, or a \-1 if an error occurs, placing the error
858269e767SBrooks Daviscode in the global variable
868269e767SBrooks Davis.Va errno .
878269e767SBrooks Davis.Sh ERRORS
888269e767SBrooks DavisThe
898269e767SBrooks Davis.Fn readlink
908269e767SBrooks Davissystem call
918269e767SBrooks Daviswill fail if:
928269e767SBrooks Davis.Bl -tag -width Er
938269e767SBrooks Davis.It Bq Er ENOTDIR
948269e767SBrooks DavisA component of the path prefix is not a directory.
958269e767SBrooks Davis.It Bq Er ENAMETOOLONG
968269e767SBrooks DavisA component of a pathname exceeded 255 characters,
978269e767SBrooks Davisor an entire path name exceeded 1023 characters.
988269e767SBrooks Davis.It Bq Er ENOENT
998269e767SBrooks DavisThe named file does not exist.
1008269e767SBrooks Davis.It Bq Er EACCES
1018269e767SBrooks DavisSearch permission is denied for a component of the path prefix.
1028269e767SBrooks Davis.It Bq Er ELOOP
1038269e767SBrooks DavisToo many symbolic links were encountered in translating the pathname.
1048269e767SBrooks Davis.It Bq Er EINVAL
1058269e767SBrooks DavisThe named file is not a symbolic link.
1068269e767SBrooks Davis.It Bq Er EIO
1078269e767SBrooks DavisAn I/O error occurred while reading from the file system.
1088269e767SBrooks Davis.It Bq Er EINTEGRITY
1098269e767SBrooks DavisCorrupted data was detected while reading from the file system.
1108269e767SBrooks Davis.It Bq Er EFAULT
1118269e767SBrooks DavisThe
1128269e767SBrooks Davis.Fa buf
1138269e767SBrooks Davisargument
1148269e767SBrooks Davisextends outside the process's allocated address space.
1158269e767SBrooks Davis.El
1168269e767SBrooks Davis.Pp
1178269e767SBrooks DavisIn addition to the errors returned by the
1188269e767SBrooks Davis.Fn readlink ,
1198269e767SBrooks Davisthe
1208269e767SBrooks Davis.Fn readlinkat
1218269e767SBrooks Davismay fail if:
1228269e767SBrooks Davis.Bl -tag -width Er
1238269e767SBrooks Davis.It Bq Er EBADF
1248269e767SBrooks DavisThe
1258269e767SBrooks Davis.Fa path
1268269e767SBrooks Davisargument does not specify an absolute path and the
1278269e767SBrooks Davis.Fa fd
1288269e767SBrooks Davisargument is neither
1298269e767SBrooks Davis.Dv AT_FDCWD
1308269e767SBrooks Davisnor a valid file descriptor open for searching.
1318269e767SBrooks Davis.It Bq Er ENOTDIR
1328269e767SBrooks DavisThe
1338269e767SBrooks Davis.Fa path
1348269e767SBrooks Davisargument is not an absolute path and
1358269e767SBrooks Davis.Fa fd
1368269e767SBrooks Davisis neither
1378269e767SBrooks Davis.Dv AT_FDCWD
1388269e767SBrooks Davisnor a file descriptor associated with a directory.
1398269e767SBrooks Davis.El
1408269e767SBrooks Davis.Sh SEE ALSO
141*aebac849SWolfram Schneider.Xr fhreadlink 2 ,
1428269e767SBrooks Davis.Xr lstat 2 ,
1438269e767SBrooks Davis.Xr stat 2 ,
1448269e767SBrooks Davis.Xr symlink 2 ,
1458269e767SBrooks Davis.Xr symlink 7
1468269e767SBrooks Davis.Sh STANDARDS
1478269e767SBrooks DavisThe
1488269e767SBrooks Davis.Fn readlinkat
1498269e767SBrooks Davissystem call follows The Open Group Extended API Set 2 specification.
1508269e767SBrooks Davis.Sh HISTORY
1518269e767SBrooks DavisThe
1528269e767SBrooks Davis.Fn readlink
1538269e767SBrooks Davissystem call appeared in
1548269e767SBrooks Davis.Bx 4.2 .
1558269e767SBrooks DavisThe
1568269e767SBrooks Davis.Fn readlinkat
1578269e767SBrooks Davissystem call appeared in
1588269e767SBrooks Davis.Fx 8.0 .
159