.Dt READLINK 2
.Os BSD 4.2
.Sh NAME
-.Nm readlink
+.Nm readlink ,
+.Nm readlinkat
.Nd read value of a symbolic link
.Sh SYNOPSIS
.Fd #include <unistd.h>
-.Ft int
-.Fn readlink "const char *path" "char *buf" "int bufsiz"
+.Ft ssize_t
+.Fo readlink
+.Fa "const char *restrict path"
+.Fa "char *restrict buf"
+.Fa "size_t bufsize"
+.Fc
+.Ft ssize_t
+.Fo readlinkat
+.Fa "int fd" "const char *restrict path" "char *restrict buf" "size_t bufsize"
+.Fc
.Sh DESCRIPTION
-.Fn Readlink
+.Fn readlink
places the contents of the symbolic link
.Fa path
in the buffer
.Fa buf ,
which has size
-.Fa bufsiz .
+.Fa bufsize .
.Nm Readlink
does not append a
.Dv NUL
character to
.Fa buf .
+.Pp
+The
+.Fn readlinkat
+system call is equivalent to
+.Fn readlink
+except in the case where
+.Fa path
+specifies a relative path.
+In this case the symbolic link whose content is read relative to the
+directory associated with the file descriptor
+.Fa fd
+instead of the current working directory.
+If
+.Fn readlinkat
+is passed the special value
+.Dv AT_FDCWD
+in the
+.Fa fd
+parameter, the current working directory is used and the behavior is
+identical to a call to
+.Fn readlink .
.Sh RETURN VALUES
The call returns the count of characters placed in the buffer
if it succeeds, or a -1 if an error occurs, placing the error
code in the global variable
.Va errno .
.Sh ERRORS
-.Fn Readlink
+.Fn readlink
will fail if:
.Bl -tag -width Er
-.It Bq Er ENOTDIR
-A component of the path prefix is not a directory.
+.\" ===========
+.It Bq Er EACCES
+Search permission is denied for a component of the path prefix.
+.\" ===========
+.It Bq Er EFAULT
+.Fa Buf
+extends outside the process's allocated address space.
+.\" ===========
+.It Bq Er EINVAL
+The named file is not a symbolic link.
+.\" ===========
+.It Bq Er EIO
+An I/O error occurred while reading from the file system.
+.\" ===========
+.It Bq Er ELOOP
+Too many symbolic links are encountered in translating the pathname.
+This is taken to be indicative of a looping symbolic link.
+.\" ===========
.It Bq Er ENAMETOOLONG
A component of a pathname exceeded
.Dv {NAME_MAX}
-characters, or an entire path name exceeded
+characters, or an entire path name
+(possibly expanded by a symbolic link) exceeded
.Dv {PATH_MAX}
characters.
+.\" ===========
.It Bq Er ENOENT
The named file does not exist.
-.It Bq Er EACCES
-Search permission is denied for a component of the path prefix.
-.It Bq Er ELOOP
-Too many symbolic links were encountered in translating the pathname.
-.It Bq Er EINVAL
-The named file is not a symbolic link.
-.It Bq Er EIO
-An I/O error occurred while reading from the file system.
-.It Bq Er EFAULT
-.Fa Buf
-extends outside the process's allocated address space.
+.\" ===========
+.It Bq Er ENOTDIR
+A component of the path prefix is not a directory.
.El
+.Pp
+In addition to the errors returned by the
+.Fn readlink ,
+the
+.Fn readlinkat
+may fail if:
+.Bl -tag -width Er
+.It Bq Er EBADF
+The
+.Fa path
+argument does not specify an absolute path and the
+.Fa fd
+argument is neither
+.Dv AT_FDCWD
+nor a valid file descriptor open for searching.
+.It Bq Er ENOTDIR
+The
+.Fa path
+argument is not an absolute path and
+.Fa fd
+is neither
+.Dv AT_FDCWD
+nor a file descriptor associated with a directory.
+.El
+.Sh LEGACY SYNOPSIS
+.Fd #include <unistd.h>
+.Pp
+.Ft int
+.br
+.Fo readlink
+.Fa "const char *path"
+.Fa "char *buf"
+.Fa "int bufsize"
+.Fc ;
+.Pp
+The function type and the type of
+.Fa bufsize
+have changed.
.Sh SEE ALSO
-.Xr stat 2 ,
.Xr lstat 2 ,
-.Xr symlink 2
-.Xr symlink 7 ,
+.Xr stat 2 ,
+.Xr symlink 2 ,
+.Xr compat 5 ,
+.Xr symlink 7
+.Sh STANDARDS
+The
+.Fn readlinkat
+system call is expected to conform to POSIX.1-2008 .
.Sh HISTORY
The
.Fn readlink
function call appeared in
.Bx 4.2 .
+The
+.Fn readlinkat
+system call appeared in OS X 10.10
projects / apple / xnu.git / blobdiff