xnu-4903.270.47.tar.gz

[apple/xnu.git] / bsd / man / man2 / readlink.2

diff --git a/bsd/man/man2/readlink.2 b/bsd/man/man2/readlink.2
index 0a604f256939460bd6ace5ca501213e66873b224..2940e9ced4848f3252485a06d6c62743a70212ba 100644 (file)
--- a/bsd/man/man2/readlink.2
+++ b/bsd/man/man2/readlink.2
@@ -37,63 +37,149 @@
 .Dt READLINK 2
 .Os BSD 4.2
 .Sh NAME
 .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>
 .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
 .Sh DESCRIPTION

-.Fn Readlink
+.Fn readlink

 places the contents of the symbolic link
 .Fa path
 in the buffer
 .Fa buf ,
 which has size
 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 .
 .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
 .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
 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}
 .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.
 .Dv {PATH_MAX}
 characters.

+.\" ===========

 .It Bq Er ENOENT
 The named file does not exist.
 .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
 .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
 .Sh SEE ALSO

-.Xr stat 2 ,

 .Xr lstat 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 .
 .Sh HISTORY
 The
 .Fn readlink
 function call appeared in
 .Bx 4.2 .

+The
+.Fn readlinkat
+system call appeared in OS X 10.10